Creating documentation with org-mode and emacs

Documentation is hard. No doubt about that. It is hard figuring out, what to document, how to document it, and most of all keeping it up to date. Personally, I have come to a realisation that one of the barriers for me, when creating documentation is how easy it is to create it.

I find having the documentation close to the code is nicer, as it can be versioned and tagged with the release of the component. Also it makes it easy to update when completing a feature. For new people looking at the component in github/gitlab/bitbucket etc a nice README is a good way to quickly get an overview.

Personally, I like that everything is kept in a textual format. It stands the test of time well. Additionally, it works well with SCM systems like git.

At times raw text is not sufficient, since a picture can say more than a thousand words, so the ability to "program" diagrams using tools like ditaa and plantuml is a nice addition.

Being an emacs user, I am also a big fan of org-mode, and the ability to incorporate source code blocks using org-babel is very nice. This means and org-mode file has the abilitiy to contain the source code for images.

For instance:

ditaa

/----------------------------------------------------------------------\
|                                                                      |
|   +--------------+     +----------------+      +----------------+    |
|   |    Service   |---->|   Deployment   |----->|      Pod       |    |
|   +--------------+     +----------------+      +----------------+    |
|                                                                      |
|                                                                      |
|                                                                      |
|                     Kubernetes Cluster                               |
\----------------------------------------------------------------------/

Becomes

This makes it pretty efficient to actually keep source of figures under version control.