Re: Suggestion for Describing Technical Documents Under Schema.org

My preference would be tack on "Topic" rather than "Document" as a suffix to the proposed sibling elements to APIReference, to better reflect that these are self-contained document objects rather than full "documents" (in DITA, multiple topics are organized via a hierarchical bookmap). That does make it more DITA-specific in terms of the naming structure, but it would more accurately describe the content type.


Here's what it would look like:

- CreativeWork

   - Article

      - TechArticle

         - APIReference

         - ConceptTopic

         - GlossEntryTopic

         - ReferenceTopic

         - TaskTopic

         - TroubleshootingTopic


Also, is this the right forum for putting together a list of potential properties for each of these elements in the hierarchy?


Cheers!



-

Keith Schengili-Roberts
Market Researcher and DITA Evangelist

IXIASOFT
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel  + 1 514 279-4942<tel:%2B%201%20514%20279-4942>  /  toll free + 1 877 279-4942<tel:%2B%201%20877%20279-4942>
robertsk@ixiasoft.com<mailto:robertsk@ixiasoft.com>  /  www.ixiasoft.com<http://cp.mcafee.com/d/FZsS83gArhohhoh76zBN4TsSCztdBNV5xMSCztdBNVZUsrjhKCOUYyMedETo7n79EzCjpkDYqJxUa9RDVWN-SZ3oG_jBPpeI_fmfSTEr5nWsKrus7fnjovW_8TuKyqeuLsKCONvAQm4T6emKDp55mVEVvVkffGhBrwqrhdECXYDuZXTLuZPtPo0agvbqltDO-6P_QDO7GOfBk5i3VriHI-ndFEKc8L6MQ1wQg60MbwAQg1eDNd40Bm3LN-5Ld40Qp-4Ph07vfp7QdIL6Y11Q5gJZM7na>


________________________________
From: Richard Wallis <richard.wallis@dataliberate.com>
Sent: July 12, 2017 2:27:25 PM
To: Keith Schengili-Roberts
Cc: public-schemaorg@w3.org
Subject: Re: Suggestion for Describing Technical Documents Under Schema.org

Hi Keith,

This seems like a useful idea and would like to see more detail on the proposal.

At this early stage I would highlight that some of the Type names (Concept, Reference, Task) are very generic words that may well have conflicting meanings in domains other than technical documentation so might benefit from being changed to something like ConceptDocument, etc.  This may also be true for properties when you get more into detail.

~Richard.



Richard Wallis
Founder, Data Liberate
http://dataliberate.com
Linkedin: http://www.linkedin.com/in/richardwallis
Twitter: @rjw

On 12 July 2017 at 17:02, Keith Schengili-Roberts <keith.roberts@ixiasoft.com<mailto:keith.roberts@ixiasoft.com>> wrote:

I have been lurking and learning in this forum for some time, and I would like to propose a schema.org<http://schema.org> structure to describe technical documentation content. My background is in DITA structured content, which comes in five distinct topic types: concept, reference, task, troubleshooting and glossentry (glossary entry). These topic types and their variants are defined in the OASIS DITA specification at:  http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/archSpec/technicalContent/dita-technicalContent-InformationTypes.html#dita_technicalContent_InformationTypes.



There is already a hierarchy in schema.org<http://schema.org> for TechArticle, which currently only contains APIReference. I suggest adding to this hierarchy new child elements that match the names of the existing DITA topic types, which would give us:



- CreativeWork

   - Article

      - TechArticle

         - APIReference

         - Concept

         - GlossEntry

         - Reference

         - Task

         - Troubleshooting


There is already a well-defined specification for these topic types, so it ought to be relatively straightforward to define the properties for each element in the hierarchy. And while I am coming from a DITA perspective, there is  technical writers creating non-structured content could also use these elements.


Am hoping for some good discussion on this. Ideally I would like to outline possible properties for each element, and then leave the tool vendors to figure out how to output the appropriate Schema.org element values.


Cheers!



-

Keith Schengili-Roberts
Market Researcher and DITA Evangelist
Chair of the OASIS DITA Adoption Committee

IXIASOFT
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel  + 1 514 279-4942<tel:%2B%201%20514%20279-4942>  /  toll free + 1 877 279-4942<tel:%2B%201%20877%20279-4942>
robertsk@ixiasoft.com<mailto:robertsk@ixiasoft.com>  /  www.ixiasoft.com<http://cp.mcafee.com/d/FZsS83gArhohhoh76zBN4TsSCztdBNV5xMSCztdBNVZUsrjhKCOUYyMedETo7n79EzCjpkDYqJxUa9RDVWN-SZ3oG_jBPpeI_fmfSTEr5nWsKrus7fnjovW_8TuKyqeuLsKCONvAQm4T6emKDp55mVEVvVkffGhBrwqrhdECXYDuZXTLuZPtPo0agvbqltDO-6P_QDO7GOfBk5i3VriHI-ndFEKc8L6MQ1wQg60MbwAQg1eDNd40Bm3LN-5Ld40Qp-4Ph07vfp7QdIL6Y11Q5gJZM7na>