Writing technical documentation using Emacs
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.
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.