I was asked a few months ago what my favorite tool is for doing technical documentation. Here is my answer.
My favorite authoring tool is not a unique tool but a combination of a language (Markdown) and a static-site generator (this is Docusaurus).
Markdown
⭐ https://www.markdownguide.org/
I used to use RoboHelp at a time, which was a well-known help-authoring tool. I loved it because of its ability to generate standalone help systems as well as web help, and the ability to view and edit HTML source code.
I started with HTML in 1998, writing the tags in notepad, linking them to an external CSS, and then, running the index.html file. I loved this simplicity and the possibility of transferring your skills to understanding the software and the technology, structuring the content, and focusing on writing, instead of using the authoring tool.
Now I write in Markdown and use an SSG to generate the HTML.
Markdown is, by definition, not a markup language. This means that you do not spend time embedding styling information in the content file. This means that, in the difference with authoring tools with GUI, you do not have to click here and there to apply styling to each group of words or click here and there to create the style sheet. With Markdown, creating a title 2 is as simple and quick as pressing two times the sharp key. Adding a note is as quick as pressing the > key.
Markdown is a content structuring language. With its simplicity, the structure of your content appears with clarity and supports your thought when documenting a feature or explaining a technical concept.
Markdown is used by many projects, platforms, and frameworks. Readme files on GitHub or GitLab are in Markdown. SSGs like Hugo, Docusaurus, Jekyll, Middleman, etc. use Markdown. Last but not least, developers are familiar with Markdown (because of GitHub/GitLab). This is a very good point when you want them to contribute to the Company’s documentation or just proofread your pages right on Git.
Docusaurus
As I mentioned at the beginning of this text, I use Docusaurus to generate my documentation websites.
Docusaurus is a project developed by the Meta Open Source team that has a strong community.
It makes sense to me that my favorite tool is open source: no licenses, a strong community that helps each other with plugins, answers, feature suggestions, and more. Sources stored on your side (in the difference with some proprietary tools that store your sources on their own servers).
Docusaurus helps build a documentation website quickly and has a large range of structuration and styling features. It is easy to customize and enrich so that your website will not look the same as the others but will reflect your Company’s image.
You can get inspired by the more than 300 different websites on the showcase page.
Docusaurus documentation is very complete, and you get started with it easily if you are familiar with docs-as-code and not afraid to approach things from behind the scenes.
Docusaurus is an authoring tool that lets you focus on your content: content pages, the architecture of the website, and navigation. The whole work on the structure files, sidebar, CSS, and content is made in your own code editor (Visual Studio Code in my case). Docusaurus interacts with GitHub or GitLab.
You can add a search engine, locate your site in many languages, and much more thanks to the plugins developed by the Docusaurus community.
Excalidraw
To be exhaustive, I complete these tools with an (open source) virtual whiteboard named Excalidraw to create diagrams. Because you often need to explain things with drawings rather than words.
