Markdown - The universal technical documentation format

"Language is the first weapon drawn in a conflict."

In the 2016 epic movie Arrival by Denis Villeneuve humanity attempts to communicate with a more advanced alien race ¹. In the IT world we face similar challenges when dealing with documentation:

1. How to convey highly technical information in a concise, easy to understand format without knowing the skill level and capabilities of the audience ?
2. How to make sure that the information is universally accessible ?
3. How to make sure that that the information is maintained and remains up to date ?
4. How to achieve all of this efficiently and at scale ?

Less is More

“You cannot understand good design if you do not understand people.” - Dieter Rams

The Markdown format is a plain text meta language that is humanly readable and can be treated as source code but it can also rendered as HTML . Markdown follows the tested and true Unix philosophy of "do one thing and do it well". It has all the functionality that a technical writer needs to produce good documentation fast and nothing else.

Choices, damn choices

"Sapir-Whorf Hypothesis: The language you speak defines the way you think"

I use markdown a lot to write a technical documentation. As a matter of fact, before even writing the first word of a particular document I make a very important decision: Which file format is best for the purpose of this document: Markdown or Microsoft Word ?

I use Microsoft Word for documents when:

• I interact with non-technical audience : executives, HR, legal finance etc.
• The document is static and never changes such as contracts.
• Only non-technical information needs to be conveyed
• No version control will be ever needed for this documents.

Basically if the business document is frozen after creation and the audience is non-technical I will use Microsft Word.

I use Microsoft Word for documents when:

• Technical documentation that involves document in code or logic
• The document will be accompanying code
• The document will be published on a web server
• The document needs to be under version control

If this is a technical document OR Code OR diagrams or version control is needed Markdown is my chosen format.

Markdown - more than a pretty face

A lot of the markdown users alludes it as an easy way to produce HTML pages with very little effort. But the true power lies much deeper: properly formatted Markdown documents with advanced visual such as tabs, syntax highlighting and mermaid diagrams results more concise documents. In turn, these documents are easier to follow by the end users and more efficient to maintain.

Tools make the difference

A lot changed since John Gruber created Markdown in 2004.

I cannot imagine creating markdown content without these tools:

• Visual Studio Code
• MKDocs with the Material
• Typora
• Zola