5.2. Languages

Markdown and reStructuredText (RST) are examples of lightweight markup languages that are commonly used for writing documentation. These languages aim to be easily readable by human programmers who are reading and writing source code. The documentation is often written as plain text files.

Markdown

Markdown’s primary objective was to create a syntax for plain text that could be easily converted to HTML [mar]. It is considered as an easy to use language and is the default markup language for creating StackOverflow or Reddit posts, GitHub readme files, and documenting Jupyter notebooks. However, it suffers from lack of a comprehensive specification (standardisation) which is important for implementing technical documentation.

• Syntax guide and best practices

reST

reStructuredText on the other hand has more built-in features for writing more complex documents, is more standardized, and has built-in support for extensions. Therefore, it is often used for creating fully fledged documentation for small or large software projects. It is used primarily in the Python programming language community for technical documentation.

• Syntax guide

• Style guide

• Cheatsheet