Software Documentation: For The Good Of The Maintenance Engineer

A couple of days ago, my wife asked me what software documentation is. I shared with her that it’s somewhat of a roadmap that helps readers understand details of the software such as how it was built and how it meant to be used. If you’ve ever written up any kind of software documentation, you’ll know that there’s nothing particularly glamorous about the process, that’s probably why it’s usually thrown onto the back-burner, at least in my experience.

I certainly used to find it a bit boring and tedious. That has since changed, and I find myself becoming more and more of an advocate for it. There are lots of good reasons for documenting software, and the documentation will mean different things to the various parties or roles that it is aimed at assisting. I want to focus more on how it’s crucial for the maintenance of the software and the engineers who will inherit the system for it’s next phase.

The “What” Of Documentation

The software project as a whole consists of several components from its system architecture, the source code, the style and programming paradigm applied during development, the particular application of logic by the engineers, the problem that the software addresses and more. If you are involved in the project from its conception, you probably wouldn’t have a hard time answering questions surrounding the aforementioned items. Documentation accounts for these and more by having written text and/or any graphical illustration that helps depict these aspects of the software in a clear and simple way so that others can easily understand the software.

Below is an example of how to graphically display the tech stack and overall architecture of an application.

The “Why” Of Documentation

As I mentioned at the start, I’m focusing particularly on the importance of documentation for the good of the team that will inherit and maintain the developed system. After software is deployed and implemented, it will typically go into the maintenance phase (or process) and this usually has no end date. You might know this from the ongoing software updates on your laptop. The software owners will want their system to change, be improved, upgraded and rid of any bugs and technical debt that has been incurred during previous development phases. That’s a great thing, and the best way we can support that process is by aiding the team of maintenance engineers with a clear, detailed and structured description of the system.

The “Nitty Gritty” Of Documentation

The list of things to include in documentation can be quite extensive, and perhaps the necessity of what to include will vary. Here are some things to potentially add in your documentation or source code that could be a big help to the maintenance team:

- An overview of the system, what it does, the problem it is meant to solve and how it solves it

- The overall system architecture

- The tech stack used

- How to install and run the software

- How to run automated unit tests

- Any prerequisites to get the system up and running

- What to do or consider in the case that the system doesn't run as it should after following the guide

- Directory structure

- Project structure

- For each component or sub system, a design description and specification

- Well commented source code, especially complex sections of the code

- A guide to known existing problems and how they can potentially be resolved or improved

- Who to contact for any kind of support

That being said…

You don’t have to be too fancy when it comes to documentation, the important things to consider are that it exists, it’s clear and readable for others. Good presentation helps because you don’t want your readers to be put off by a poor structure/layout, bad grammar or incorrect spelling. Get started by adding and editing “README.md” files to your project for the good of the team who will have to build on what you’ve developed.

Software Documentation: For The Good Of The Maintenance Engineer was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.