Creating re-usable chunks (conref) in Jekyll versus DITA
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.
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:
Where you want to re-use the note, you add:
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:
Where I want to insert the note, I include the following:
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:
To insert the content from the notes.yml file, you add this in your page:
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.
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:
In my data file, I could add this formatting:
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:
Most of my notes aren't reused from data files, so here's a typical instance of a note with this formatting:
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:
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 a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.