Holy Grail question of Tech Documentation is the one from the title: How to Maximize Content Reuse of Tech Documentation?
We offer very simple and affordable solution: Use MarkDown and Git Repos
Why those?
Well, with these tools you can achieve maximized results, all you need is to keep single source of truth in MarkDown, which is building block of many tools and approaches. The reasons which contribute to the statement:
- UC1 - You can always write content direcly to MarkDown in your content repo - random articles, design docs, or internal writeups reuse
- UC2 - There are widly spread tools which convert MarkDown into HTML, called Static Site Generators (SSGs) - website content reuse
- UC3 - Most of the Wiki providers are Git based (all content is in the background kept as Git project written in MarkDown format) - examples are GitHub, GitLab and Azure DevOps wiki pages (the only exception is Atlassian Confluence) - Wiki pages content reuse
In the further lines we will elaborate those three aspects.
Static Site Generators
Static Site Generators (SSG) convert practicaly static MarkDown content into HTML websites. The most relevant are Jekyll, Next.js, Hugo, Gatsby and the others.
For instance, available Jekyll themes could be found on Jekyll themes IO website or Jekyll themes org website
GitHub Pages and GitLab Pages services for static content are based on SSGs and both supporting Jekyll SSG.
These are the examples of the docs source content on: GitHub. Microsoft
Microsoft has introduced even a docs feedback system based on GitHub functionalities and ticketing system
Wiki Content
Major Git providers also provide Git based Wiki pages:
For all of them is common that HTML is frontend for creation, however all of them are kept in Git repos as MarkDown files. That helps a lot to our goal of unifying the way of storing the Tech Documentation content.
Native MarkDown Content
There are many tools available for writing native MarkDown. Some examples are given on Oberlo’s blog post on markdown editors
Our Recommended Approach
Essentially, all major players are converging to MarkDown and Git. This is completely aligned with our approach, since all of the created content can be easily reused with our recommended approach and custom fancy docs, in corporate templates, can be created in couple of seconds for internal or external publishing.
Recommended workflow is outlined on the PlantUML diagram below
