Diagrams and Central Documentation

Overview

In this lesson, we'll study the types of diagrams used in documentation. We'll use Graphviz and Mermaid diagrams as examples. This lesson will also cover the purpose of concise documentation and how to make a brief yet useful README file.

Types of diagrams

Adding pictures to documentation makes it quicker to understand what's going on. It’s better if this is done with a tool that can be compiled from a source which can then be kept in source control. Let’s discuss a few types of diagrams that we can use.

Graphviz

Graphviz is a great way to document software architecture. Graphviz is a suite of tools that allow diagrams to be generated from a simple text file. These diagrams and the associated source files can be put into a Git repository. These diagrams don’t have to be very sophisticated to be useful. A simple starting point is to use inputs and outputs. This allows developers to see collaborators of a component. Here is a sample architecture.dot file: