My Favorite Tools
Markdown, Docusaurus & Diagrams — My Happy Trio for Docs
A while back, someone asked me what tool I use for technical documentation — and instead of picking just one, I realized my setup is more of a creative trio.
I write in Markdown, build with Docusaurus, and sketch with Excalidraw. In this post, I’ll share why this combo works so well for me and how it keeps writing both simple and powerful.
🟢 I was asked a few months ago what my favorite tool is for technical documentation. Here is my answer.
My favorite authoring setup isn't a single tool – it's a combination of a language (Markdown) and a static-site generator (currently, Docusaurus).
Markdown
⭐ https://www.markdownguide.org/
I used to use RoboHelp for 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
- unlike 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 the # key twice. 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, localize your site, and much more thanks to the plugins developed by the Docusaurus community.
* Docs-as-code is a documentation approach where technical content is written, reviewed, and published using the same tools and workflows as software development.
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.
Excalidraw is a virtual whiteboard that lets you create diagrams with a charming, hand-drawn aesthetic — as if they were sketched on a paper board with a marker. From a library of basic tools (shapes, arrows, lines, text, and colors) you can draw anything with a natural, sketch-like vibe. It is useful whether you're diagramming a technical flow, brainstorming ideas, or illustrating a concept.