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
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.
Microsoft has introduced even a docs feedback system based on GitHub functionalities and ticketing system
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