On the first day of WriteTheDocs in Prague last week, Luc Perkins gave a lightning talk about a workstyle he called “object-oriented documentation”. When following this method you aim to create documentation in re-usable components that can then be mixed and merged. Ideally, you’d this way be able to reuse them in completely different output formats like tutorials, blog posts, reference guides, and so on.
In the talk, Luc gave the example of “externalizing” concept definitions that can then be reused wherever necessary, something you might normally associated with a glossary (for instance, Sphinx). On second thought it’s more akin to the idea of something like assemblies in DocBook, where you can combine “topics” into completely new documents.
In general, though, I feel like my first hunch regarding “glossary-like” content might be the most practical use-case for this style of documentation. Pretty much anything that eventually might be used as an aside, tooltip, or similar in a larger document would be - for me - a prime candidate for this style of writing.
Systems like Hugo or Jekyll support different types of content. In
Jekyll these are called collections while Hugo has content
types. At first I thought that the concept Luc described would
perhaps better be called “component-based documentation” but that
would ignore that we are actually talking about various “classes of
content” here. Glossary-entries are just one class here while another
could be “screenshots”, “keyboard shortcuts”, and so on. Combined with
$.Site.Data calls these could either be embedded or just
served as standalone content.
I would love to see that being applied somewhere on a larger scale, though. If you know of a public repository that uses this documentation style, please let me know!
Do you want to give me feedback about this article in private? Please send it to email@example.com.
Alternatively, this website also supports Webmentions. If you write a post on a blog that supports this technique, I should get notified about your link 🙂