RST- My Preference for Technical Documentation

I am a technical writer who currently works in the developer documentation space. Markdown has become the preferred markup language for documentation in this space. Most modern tools such as Swagger, Stoplight, Doxygen, JSDoc, TypeDoc, and Acrolinx handle Markdown syntax by default. At my workplace, we choose Markdown over XML/DITA for smaller end-user documentation projects. However, I prefer to use reStructuredText (RST) over Markdown for my work. In this article, I will try to explain what makes RST so attractive to me.

What is RST?

Like Markdown, RST is a lightweight markup language that was designed to create technical documentation. It was created as a part of the Docutils project by the Python Documentation Special Interest Group. Although it was originally designed as Python’s answer to JavaDoc, I primarily use RST for documenting REST APIs and JavaScript/Typescript Libraries. For more information on RST, see Introduction to reStructuredText on the Write the Docs website.

Why RST and not Markdown?

Automatically catch formatting violations

RST provides a stronger implementation of semantics than Markdown. Sphinx, the static site generator that converts RST to HTML, catches many formatting violations when I generate HTML. This does not mean that I can skip checking the generated HTML. It is just that I am assured that the most significant formatting issues will get detected automatically. 

Easily create complex tables

Official Markdown does not support tables. Github Flavored Markdown supports tables, but only simple tables. If you need tables that contain merged cells, you must use HTML.

RST supports four different ways of building tables: Grid Tables, Simple Tables, CSV Tables, and List Tables. With all this, I find that there is no table that RST cannot handle. Sometimes, I even insert tables within table cells, which is no big deal in RST.

A special note on CSV Tables: CSV Tables let me reference table data from an external CSV file. So, I can create and maintain table data with a tool like Microsoft Excel, which has been purpose-built to handle tabular data.

Write once, use in multiple topics

I write documentation for several APIs. Content for topics such as Authentication, Error Handling, Webhooks, Rate Limits, and Quotas, repeats much of the same content across the different APIs. RST has a feature named Include Directives that lets me include a document fragment from one RST file in another, just like how DITA implements content references. I have set up a library of reusable content, which I use to insert common content into topics across multiple API products.

Even within the same project I sometimes need to use the same set of paragraphs in more than one topic. Include Directives let me reuse content much in the same way that $ref tags allow content reuse in OpenAPI documents. I write once and reuse across multiple topics.

For more information on Include Directives, see Including an External Document Fragment on the Docutils website.

Automatically test example code

The literalinclude directive feature is perhaps the game changer for me. It lets me extract blocks of code directly from source code files and include them as example code blocks in an RST topic. I can select the block of code to extract by specifying line numbers or markers. This means that the example code in documentation can come from a functional project and the source code of this project can be tested automatically every time an API is built. The ability to unit test example code helps me keep the documentation synchronized with an ever-changing codebase.

See Show Example Code from the Read the Docs web site for more information on code-block directives. Also, look at the post on extracting code blocks using markers on Stack Overflow.

In Conclusion

RST supports many more cool features. I have only mentioned the features that can make a significant difference in the documentation process. Besides the built-in capabilities of RST, we have developed in-house tools to generate API References from OpenAPI documents and JSDoc comments. We are currently looking at building a Typedoc-to-RST tool for TypeScript libraries.

On a different note, at first glance, RST and Markdown look similar. The effort to learn RST is not significantly different from the effort to learn Markdown. RST can do everything that Markdown can do. If you limit yourself to Github Flavored Markdown features, you can get Github to render RST files just like how it renders Markdown.

The most recent version of Sphinx, the static site generator that converts RST to HTML, now supports Markdown as well. I can hence have documentation projects that contain a mix of Markdown and RST files. I however will continue to keep my projects in RST because of the built-in safeguards that help me keep the documentation up-to-date, and hence, trustworthy. 

References

• Documenting APIs - More about Markdown https://idratherbewriting.com/learnapidoc/pubapis_markdown.html#RST_and_asciidoc
• Why You Shouldn't Use Markdown for Documentation https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
• Markup Languages: Comparing reStructuredText and Markdown https://www.jungledisk.com/blog/2017/01/20/restructuredtext-vs-markdown/
• reStructuredText vs Markdown for documentation http://www.zverovich.net/2016/06/16/RST-vs-markdown.html
• reStructuredText vs. Markdown for technical documentation https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
• Markdown Flavors https://github.com/commonmark/CommonMark/wiki/Markdown-Flavors
• Daring Fireball - The Philosophy of Markdown https://daringfireball.net/projects/markdown/