Applying structured data

Using controlled templates to write DITA and Schema.org compliant content helps us write more functionally.

Jekyll is a great way for technical writers to generate topic based web content due to its templating function. A good way to apply structured data is to mix DITA topic types and Schema.org together and use layout templates to generate the output. For example, if we write a topic that we define as a concept, we create one concept.md template to write the content and then a corresponding concept.html layout to display the content. Within this concept.html layout, we can add DITA XML data or Schema.org metadata. When we generate the topic, our XML and structured data will appear in the metadata.

The two examples below show firstly a topic template concept.md. We’d use this as our key content template where we edit the actual text we want to appear. Secondly, the XML snippet concept.xml that we would insert into our final output via a Jekyll layout template. This would include DITA tags in our final output in the metadata. We would repeat this for Schema.org type information.

Using topic based authoring techniques like coupled with structured data concepts ensure that our topics are short and to the point.

Example

---
# concept.md
# This is a strict template for concept topics adapted
# from https://www.oxygenxml.com/dita/1.3/specs/archSpec/technicalContent/dita-concept-topic.html
layout: concept # _layouts/concept.html
title: # required
description: # required, text or markdown
conbody: # required, text or markdown
example: #  text or markdown
---

<!-- concept.xml -->
<concept id="concept">
  <title>{{concept.title}}</title>
  <shortdesc>{{concept.description}}</shortdesc>
  <conbody>
    {{concept.conbody}}
    <example>{{concept.example}}</example>
  </conbody>
</concept>

See also

• Technical writing and DITA

• Topic overview