In this post I will share with you what type of tools I am using to quickly and easily write technical documentation.

Introduction

In our job we always have to write and share documentation. I had a lot of thoughts on this subject, and I finally found a good solution for me last year. I based all my work on markdown files.

Markdown language

Markdown is a plain text formatting system created in 2004 by John Gruber and Aaron Swartz. It was developed to allow people to compose richly formatted text for the web. At its most basic, markdown is a text-to-HTML conversion tool for web writers. When it is used, it converts text to structurally valid XHTML and HTML.

I discovered this formatting in 2020 when I was searching for a good and quick way to rapidly present my work, without spending time on the design of my documentation. And also because I love coding and I found it really fun that I can write text and at the same time small code inside it (html part).

Since 2021, I wrote everything in markdown, my technical documentation but also my meeting notes, my planning, my tasks list and this blog as well.

I can also directly include my schematics with mermaid-js inside my markdown and that's just perfect.
Other big pros of using markdown is that all your documentation and schematics can be manage directly in your base code and the merge part is not a nightmare.

If you want a description of how to use the markdown I recommend you the following link.

In french
https://blog.wax-o.com/2014/04/tutoriel-un-guide-pour-bien-commencer-avec-markdown/
or in english
https://www.wpexplorer.com/wp-markdown-wordpress-guide/

for mermaid_js it's here
https://mermaid-js.github.io/mermaid/#/

Tools I use

Typora

For my daily work, I use typora. You have to pay for a license, but I think the license is not expensive, and the model of licensing is very great. I highly recommend this tool even if you have to pay.
https://typora.io/

Unotes in vsCode

For those who prefer a complete integrated tool, I recommend to use Unotes inside vscode. The main raison why I like this tool is that you can directly see what your are typing
https://marketplace.visualstudio.com/items?itemName=ryanmcalister.Unotes

wordpress

For this blog I simply use the markdown extension : githuber
https://github.com/terrylinooo/githuber-md

You can directly see what the result of what you type is in markdown

mkdocs

I use this tool for my technical documentation with a full markdown support
https://www.mkdocs.org/

My Feedback

I appreciate this language. It's quick to learn and that changed my way of working and writing things. I wish I had discovered this language and typora earlier .

I can pretty much do everything with markdown, the only limit that I see today is the paging. The header/footer page is not good at the moment, especially when you want to export the documentation in pdf or word. This is not ready, so I need to work on my documentation again when I want to make it official and in a professional format.

There is also a difference in the tools you use. The majority of the markdown is standard but some features are non-standard. For example, in typora I can do more extra code than in Unotes and my document doesn't have the same final design. That can be very time consuming when you are sharing documentation between team members, who will use different software for reading mk files.

Conclusion

I highly recommend using this type of writing and I am pretty sure every coding documentation will be done with this syntax in a few years and I hope the little negative feedback I found will be quickly implemented in this language, as software goes quicker and quicker.