Text-based Diagramming in Writing Technical Documentation

Explore open-source solutions for writing technical documentation with diagrams.

alpha2phi

--

Photo by Annie Spratt on Unsplash

Overview

In a previous article, I described a text-based approach to draw different kinds of diagrams and serve them programmatically. Let’s explore various open-source solutions that can be leveraged to write technical documentation, along with using a text-based approach for diagramming.

There are several advantages of using a text-based approach for diagramming.

  • Version control is easy. The developer can track changes made to the diagrams easily. Diagrams are now treated as part of your source code or document repository.
  • Using open-source libraries and tools for writing technical documentation, and the Mermaid Javascript library for diagramming and charting, I can easily generate and serve the documentation.
  • Standardization. No more diagrams with different styles, and the presentation is always consistent.

Emacs

Let’s start with Emacs. Though it is a nearly 40 years old editor, Emacs is still one of the best and widely used editors with large support from the communities.

In a previous article, I demonstrated to you how to write and generate technical documentation using Emacs.

Using mermaid-cli and the ob-mermaid Emacs packages, I can generate diagrams and charts within Emacs and bundle them with the documentation.

Install mermaid-cli globally using npm.

npm i -g @mermaid-js/mermaid-cli

Install the Emacs mermaid package.

(use-package ob-mermaid
:custom
(setq ob-mermaid-cli-path "/usr/bin/mmdc")
)

Create a mermaid diagram.

#+begin_src mermaid :file diagram.png
journey
title My working day
section Go to work
Make tea: 5: Me…

--

--

alpha2phi

Software engineer, Data Science and ML practitioner.