HOW TO SHOWCASE SOFTWARE DOCUMENTATION

Documentation is the blueprint of software (source: pikist.com)

In IT, you can see more people realizing the importance of software documentation. With switching to agile processes, most teams also stopped designing their software in detail. However, with the development of Agile Documentation philosophy, software designing and documentation lately finds their place and value again. Some people even consider a software application without documentation as a horror house nowadays. I agree with them because there are traps everywhere in a legacy structure and anything can fall on you at any move. With a legacy setup without any documentation, you can even hear music coming from the code while you work on it. A song that is similar to the one from the legendary Super Mario game, the one when he is underground.

The choice of display over writing (created with PlantUML)

The comparison above is not the ideal way to show that software documentation and UML diagrams are indeed helpful but you get the general gist. As the saying goes:

Ink is better than the best memory.

— Chinese proverb

Whether to document your code is a question of whether you want to work in a secure work environment or not. Apart from that discussion, another important aspect of this topic is where to store and display those documents. A work of art that is not prominently displayed for everyone to see is a wasted effort. If nobody knows of its existence, then nobody can effectively consider it as a work of art. People need to know that they have it.

In my team, we had long discussions about what to use for documentation of our software. The discussions focused on three aspects.

• What to use for generating UML diagrams?
• Where to store them? How to achieve version control?
• How to show them to stakeholders?

TL;DR: We have decided on using PlantUML with GitBook on GitLab.

What to use for generating UML diagrams?

There are dozens of tools to use but I will focus on three of them.

Diagrams.net (formerly Draw.io)

A screenshot from diagrams.net UI (source: diagrams.net)

One of the oldest in the industry. In the past, it was even served as a file storage option in Google Drive.

✅ Very easy to use, anyone can draw diagrams using their drag & drop UI
✅ Has lots of ready to use templates and samples (8 for UML)
✅ Free to use
❌ Not good for collaborative working
❌ Not suitable for highly-technical drawings
❌ Not presenting a good way for tracking changes on files

Storage (version control) options: Google Drive, Dropbox, One Drive, Git

Showcase options: Own UI, Google Drive, Confluence

Conclusion: Suitable for small teams or individuals with less need for higly-technical documentation

Lucidchart

An overview of Lucidchart (credit Lucidchart.com)

Arguably the most popular tool in the industry. It was also served as a file storage option in Google Drive in the past. A “premium” tool, so to say. It has lots of benefits, compared to Diagrams.net. You can check the comparison of the two, made by Lucidchart.

✅ Very easy to use, anyone can draw diagrams using their drag & drop UI
✅ Has lots of ready to use templates and samples (50+ for UML)
✅ Has a very good collaboration system where you can open discussions on every object with possible resolutions
✅ Suitable for tracking changes on files properly, keeps revision history
❌ Comes with a price (Team package is monthly €8.00 per user)

Storage (version control) options: Google Drive, One Drive, Git

Showcase options: Own UI, Google Drive, Confluence, Visio

Conclusion: Suitable for small or big teams with any kind of need for technical documentation, if there is budget for it

PlantUML

An overview of PlantUML (credit Eclipse.org)

A techy alternative where you code your diagrams. Not a tool actually, more like a framework or language. Best thing about PlantUML is you spend less time on sizing your shapes or aligning their edges. You leave the visual adjustments to the application and focus on the context itself.

✅ Has an important advantage, when you code your documentation, the algorithm of your product is also being built at the same time since you are using conditionals, loops, flows, etc.
✅ Has plugins for all modern IDEs such as PhpStorm, VSCode, Atom, etc.
✅ Last but not least, since it is pure code, it is enabling blind people to create diagrams too
❌ Not suitable for non-tech people (it is my personal favorite as a “tech person” by the way)

Storage (version control) options: Google Drive, Dropbox, Git

Showcase option: Own UI (via their online renderer), Confluence, GitBook

Conclusion: Suitable only for tech teams, highly customizable

Where to store them?

As mentioned above, you have plenty of storage options. I will focus on Google Drive, Confluence and GitLab.

Google Drive

A simple but powerful storage for non-techy structures. If you are using Diagrams.net or Lucidchart and also G Suite, Google Drive is a strong candidate to store your documents in.

✅ Stores previous versions of the file
✅ Keeps track of who updated them
✅ Supports reverting the history

Confluence

Atlassian magic, BFF of JIRA. In Computers Electronics & Technology industry, almost 20% of the companies are using JIRA and Confluence (according to similartech.com). It is simple why they are so popular. They present countless integrations with an open marketplace and plenty of plugins. Whichever UML tool you use doesn’t matter, there is a Confluence plugin to render it.

✅ Confluence is your friend to both store and showcase them, if you do not have giant documents or limited space in your JIRA cloud
✅ Gives the ability to integrate a storage option and use Confluence only for displaying
❌ Fails on version controlling, does not keep versions

GitLab

Nest for nerds, a place where we feel safe and warm. King of history and versions who rules every one of them. You may not always be able to use GitLab for storage. However, if you are able, you will love it.

✅ With CI/CD pipeline configurations and additional plugins, it is highly customizable. Sky is the limit, some might say
❌ In the meantime, when something is highly configurable, generally it is also highly fragile or hard to manage

You will understand better when I give more info on configuring GitLab to host your PlantUML diagrams.

How to show them to stakeholders?

There is nothing special to mention about the three options when it comes to showcasing. Because what is desired is simple; we want to preview diagrams and navigate between them. That’s it. Simple, yet effective. Except for extra features for collaborating, all three of them have the above ability.

Google Drive

✅ You don’t need to configure anything. It is already configured by default and you can immediately showcase your Diagrams.net or Lucidchart diagrams with it

Confluence

✅ Gives you the ability to insert your diagrams into texts with widgets
❌ You need to search the marketplace for plugins that serve your purpose

GitLab

✅ Gives you the ability to store your diagrams without configuring anything and as Git stores a very long history on repositories, every update on those files is recorded, can easily be reverted
❌ Needs extras for displaying the diagrams if they are not plain images

Using PlantUML and GitLab to store and display

The first thing you need to know is that PlantUML diagrams are made of code, therefore they need to be compiled and rendered. It is using Java and Graphviz to generate diagrams with its domain-driven coding language. In order to achieve that, you need to compile your diagrams locally or you need to use a server for that. There is a publicly available server by PlantUML for rendering. If you do not want to share your company documents on a public server, then there is a “build your own server” option. The detailed documentation is available on GitHub. Also, the “official” server often suffers outages when it is heavily used, since it is the most well-known public PlantUML server.

You can safely store your *.puml files in GitLab repositories. In order to preview them in Markdown files as inline text widgets, you need a plugin to render PlantUML codes. If you want to showcase your rendered diagrams publicly, you need GitBook for that.

The plugin we chose is called gitbook-plugin-graphviz-and-plant-uml. We chose this plugin because it enables us to define our own server to be used for rendering the diagrams.

More plugins for GitBook can be found by searching the word “gitbook-plugin-” on NPM website since all plugins use that naming convention.

An important note in here is that these plugins are actually not rendering *.puml files, they render PlantUML code in *.md Markdown files. So the trick to make GitBook render PlantUML files is below.

• Create 2 files called book.json for GitBook configuration and website.css for styling the book (optional). A sample book.json file is below:

• Create a bash script for CI/CD pipeline in .gitlab-ci.yml to convert .puml files to renderable .md files with opening and closing tags

Now your GitBook is published under the pre-defined GitLab Pages URL. Do not forget to create and regularly update a SUMMARY.md file which is crucial for GitBook navigation.

For a more solid approach, you can check the sample boilerplate I created. For the rest, keep documenting!

I want to acknowledge the people who were very helpful to me while I was trying to build this structure: Emre Piskin, Calvin Barelds and Potherca.