How to create and maintain good software documentation
Tags: How To, Plantuml, Software Development, Documentation, Cloud Computing

Implementation

In this section we will look at different tools, frameworks and documentation models to fulfill documentation characteristics requirements. We are going to focus mostly on open source tools and standards.

Below diagrams shows tools, frameworks and standards we will use to implement our documentation strategy later on.

SHARP

Tools and Standards

Now, we will focus on specific tools and standards that can be used to implement our strategy. Please note that there are almost always alternatives to each tool, framework or standard. For simplicity I’m recommending the ones I’m familiar with that I know work well together. You can think about it as a starter pack for good software documentation.

Simple

To keep documentation simple, we need a suitable medium. Most documentations nowadays are either in MS Word or pdf, but I believe that Markdown is a better choice. Markdown is a lightweight, HTML-like markup language that is very common in software projects (README.md files etc). It is more scalable and easy for developers to use markdown rather than complex text editors like MS Word. Added bonus is that markdown files can be directly edited in IDEs or code editors like Visual Studio, Visual Studio Code, Atom or WebSharper etc.

Holistic

There is no specific tool that I know of that will make your documentation understandable by all stakeholders ;). You will need to make an effort to do so. Defining common vocabulary as well as logical naming conventions is a good first step!

Automated

PlantUML is one of my favorite tools for rendering diagrams. Diagrams in PlantUML follow “…as code” movement. Where diagram is generated on the fly from simple domain specific language.

One important characteristics of PlantUML is ability to render diagrams on the fly without converting them into pictures. This is very useful and allows all online documentation that links to centralized diagrams repository to be updated automatically

In order to document API resources (REST) or methods (RPC) in an automated way, we can use documentation generators like Swagger that generate documentation from code comments or from API Spec.

Each separate markdown file or whole documentation repository can be imported into HackMD where all stakeholders can participate in a live collaboration session to add notes and develop documentation together. HackMD in and of itself is a very powerful tool with other useful features, check it out! After importing particular markdown file, it can be exported back to a repository.

Finally, documentation for particular software project should be encapsulated in its own repository, linking markdown files and other artifacts from other repositories belonging to the same software project. Part of CI/CD pipeline should be automated building and deployment of the documentation artifacts.

Automating as much as possible will ensure that documentation is maintained over time.

Reusable

To make documentation reusable we need to agree and follow on standards and best practices that all software projects will adhere to.

Here are some standards and models that I find helpful in defining documentation outline.

TOGAF is and Enterprise Architecture Methodology and is mostly aimed at enterprise architects, providing guidelines and models for high level enterprise architectures.

For development teams, documentation following TOGAF standard will likely be and upstream reference that allows alignment with global company architecture standards.

arc42 is a template for communication and documentation. It creates scaffolding and structure helping place topics in right context appropriately addressing various stakeholders.

C4 model helps with putting structure around diagrams and visual artifacts for software documentation. It fits very well with arc42 approach.

PlantUML was mentioned before in context of diagrams automation rendering, but it is an amazing tool for visualizing software in an “…as code” way.

PlantUML has a lot of plugins for different programming languages allowing for quick diagrams generation based on source code. There are also plugins that can do reverse operation, namely generate code based on planUML class diagram.

We are not going to dive deeper into different software diagram types and their usage, but suffice to say they are all supported by PlantUML.

Portable

Our documentation so far is based on open standards, uses open source flexible and powerful tools. Now it’s time to make it available to all stakeholders.

In order to make documentation portable, we need to be able to generate it based on our markdown files and present in an easily consumable form. Best way to do it is deliver documentation as a web page based on static files or HTML generated on the fly.

Docsify is one of my favorite tools for serving documentation transformed to HTML from markdown files based on a few simple configuration files. You can see results of this transformation on my website dedicated to preparation for Docker Certified Associate.

Another approach is to serve documentation a static website that is build during build process (part of CI/CD pipeline). There are plenty of static site generators, which by the way are useful in many more scenarios than generated documentation. One of my favorite generators is Hugo

Once our documentation is ready and CI/CD pipeline is created, we can deploy it to a hosting provider. One such provider is Netlify, but there are many others. If you are interested in how static sites can be deployed, check out my blog about this topic.

Advanced topics

There are three additional topics that are more advanced, but I think it’s worth discussing them briefly. If you are interested, please study further, links are provided.

Developer Portals

Automated Deployment Diagrams

File conversion

Developer portals enable development teams to not only share common documentation but much more. Spotify recently donated to CNFC their home grown developer portal that has smart documentation as part of its offering.

Deployment diagrams, especially on public cloud providers should represent actual state of the infrastructure. Such automation is possible with Hava (please note that this is a commercial product). There was also a tool called Arcentry which was open source, but is since discontinued.

Finally, to satisfy corporate requirements around document formats, like pdf or docx, you can use Pandoc to quickly convert between different document types. Pandoc has rich support for various formats, not only pdf or docx, but those are most common.

Putting it all together

Below diagram shows how one centralized documentation repository per product or project could be used to maintain software documentation including files from different repositories compose software (for example with microservices architecture).