Creating re-usable chunks (conref) in Jekyll versus DITA
In my previous post, I explained how to do variables and conditional processing in Jekyll. One of the commenters wondered about how you create "intelligent content" with Jekyll:
how does a Jekyll (or similar) approach let us create intelligent content?
There was a recent conference in San Francisco focused on intelligent content, and one of the attendees (Trinity Hartman) wrote a brief description describing just what intelligent content is. Trinity says intelligent content has four characteristics:
Discoverable: You need search-optimized content if you want online shoppers to find your products
Reusable: Every time you change your product, you should be able to easily update your content, too
Reconfigurable: If your content is easy to modify, you can create retailer-specific product descriptions with minimal effort
Adaptable: Your content should be chunked in such a way that it's easy to read on all kinds of devices, including mobile phones.
— see Intelligent Content: Adapt or Get Left Behind
Let's look at the two middle attributes here: reusable and reconfigurable (I'll save the others for another post). To make your content intelligent (as opposed to dull or dimwitted), the basic approach is to chunk your content into little topics so that you can mix and match the chunks in places you need them. By chunking your content into little bits, you have greater flexibility to arrange them into different outputs, reusing content as needed.
I explored chunking previously in a post called The Importance of Chunking for Sorting. In that post, I noted how rock cairns (guide signs for hikers that consist of stacked rocks) can be arranged in many different ways because of their small chunks:
Contrast the small rocks approach with big rocks, which have little capacity for varied arrangements:
It makes sense to chunk material into small pieces if you want to construct a lot of different arrangements.
See also Topic chunking and the broken alarm clock, in which I respond to a point Mark Baker makes about the effects of chunking too small. If you break apart an alarm clock into its little pieces, those little pieces may not make sense in isolation. You may end up with topics that no longer make sense on their own but require someone to constantly navigate a TOC to construct a coherent set of information.
How you chunk in DITA
In the DITA world, "conref" is synonymous with re-use. People like the term so much, they use it as a verb, as in, Hey, I need to "conref" this information here....
DITA uses the conref element for chunking. For example, if you have a note that you're reusing, you create a topic and put the note in it like this:
<topic id="topic_123">
...
<note type="warning" id="bolt_warning">Don't overtighten the bolts, as it may cause stripping.</note>Where you want to re-use the note, you add:
<note conref="notes.dita#topic_123/bolt_warning"/>
There is one limitation with this approach, though. The element must be valid where you insert it. For example, you can only use this note in places where the note element is valid.
Notes are valid in a lot of places, so it wouldn't pose much of a problem. But suppose you have an entire section that you're reusing. You couldn't insert that in both a strict task topic as well as a concept topic.
DITA also offers a conref range option. If you're re-using several steps, or several paragraphs, you can start with conref and end with conrefend to mark where the re-use should stop. For details, see DITA: Conref.
How to "conref" in Jekyll
In Jekyll, conrefs are called "includes" (which is a more traditional term for re-use). When you want to include content from another file, you add an include.
Using the same example as before, to reuse a note, I could create a file called bolt_note.md and add this content:
Warning: Don't overtighten the bolts, as it may cause stripping.
Where I want to insert the note, I include the following:
{% include bolt_note.md %}
Because Jekyll doesn't enforce information typing, I could insert this note anywhere I wanted, without worrying about whether it was valid or not.
Includes don't allow you to pull different parts of the same file, though. For example, if I had one file that contained all my notes, I couldn't select a specific note from that file using includes. Includes pulls in the whole file.
However, if you have a of small content to re-use like this, there's another way to re-use it. You can store the content inside a YML file that you put in a _data folder in your project. For example, I could create a file called notes.yml stored in the _data folder.
In data files, you use YML syntax, like this:
bolt_note: "Warning: Don't overtighten the bolts, as it may cause stripping."
To insert the content from the notes.yml file, you add this in your page:
{{site.data.notes.bolt_note}}
If you read my last post (Variables and conditional processing), you'll see a similar technique. Instead of using site.audience, which gets info from the configuration file, you use site.data.notes to get info from the notes.yml file inside the _data folder.
(Through the data_source property in your configuration file, you can specify a different data folder source if you don't want to use the default _data folder. This way you can have different data sources for different configuration files.)
Now suppose you want to add some formatting to the note style. If you have Bootstrap integrated, the official style might look like this:
<div class="bs-callout bs-callout-warning"><b>Warning:</b> Don't overtighten the bolts, as it may cause stripping.</div>
In my data file, I could add this formatting:
bolt_note: "<div class='bs-callout bs-callout-warning'><b>Warning:</b> Don't overtighten the bolts, as it may cause stripping.</div>"
However, this kind of approach leads to possible variation with the note style, since I may have lots of warnings. What if I decide to change the style later on? I don't want to have to change dozens of warning styles.
To keep the note style in one place, I can put the note style into its own data file. I might create a file called alerts.yml and store my warning note style there:
warning: "<div class="bs-callout bs-callout-warning"><b>Warning:</b>"
And this:
end: "</div>"
Most of my notes aren't reused from data files, so here's a typical instance of a note with this formatting:
{{site.data.alerts.warning}} Make sure that, when loosening your pedal, you turn your left wheel <i>clockwise</i> and the right wheel counterclockwise. {{site.data.alerts.end}}
If I wanted to re-use the previous example of the bolt-tightening note inside of this same re-used warning formatting, I could do this:
{{site.data.alerts.warning}} {{site.data.notes.bolt_note}} {{site.data.alerts.end}}
That last example isn't so pretty, since it consists entirely of references to other content. There are probably more elegant ways to do it using a Ruby plugin, but once you start using plugins, you can no longer have Github Pages rebuild your content in the repository.
At any rate, Jekyll provides multiple options for content re-use, which opens up some more possibilities.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.