Writing Technical Documentation with Emacs

alpha2phi
5 min readApr 17, 2021

Writing technical documentation using Emacs Org mode.

Writing Tech Doc with Emacs

Overview

Developers normally dislike documentation. However, it is inevitable that you have to spend time documenting the applications, libraries, or SDK that you developed. For project documentation, we have tools like MkDocs, Jekyll, Sphinx, Hugo, Gatsby, and many others that can be used.

However, one major issue with using these tools is that your application code and documentation are separated. E.g. if you need to document a code snippet, you have to run it separately and then paste the code and results into the document. Over time this is going to be a maintenance issue to keep your documentation updated.

In my previous article, I talked about literate programming using Jupyter notebook. Using this approach, your code and documentation will always be in sync. In this article, I am going to use Emacs Org mode to write technical documentation.

Setup

Emacs comes default with Org mode installed. However, if you want to use the latest version, just type M-x package-install RET org RET (Make sure you configure Org ELPA as one of your package repositories). For this article, I am going to use Org mode 9.3. You can check your Org mode version by typing M-x org-version RET.

If you are just started with Emacs, do go through my previous articles. You can refer to my dotfiles in this repository.

Org-Babel

--

--

alpha2phi

Software engineer, Data Science and ML practitioner.