“Is there some documentation how I have to configure my IDE to integrate and debug those components?” – “Yes. Have a look at the Wiki. Or maybe there is some PDF in the VCS somewhere. It might be pretty outdated though.” Sounds familiar?

I’ve been in that situation countless times. User documentation is grudgingly maintained at the minimal acceptable quality level. Internal documentation for developers, integrators and testers is only maintained when we feel like it. And let’s face it – writing documentation is not exactly what we joined this profession for in the first place.

Clean documentation is a matter of professionalism

It’s basically the same game as with clean code: We can get by with the minimal effort. We can ship software that works more or less, with not too many bugs, accompanied by some halfhearted documentation for the users.

Or we can strive to write something that lasts and is maintainable. We can put in some effort and professional pride to make us more productive in the end. Doing so by writing clean code is a good start, but it’s not everything we can do.

Having good and clean documentation on how to do the common project specific tasks goes the same way towards maintainability as clean code. The difference is only what is made more maintainable: In one case it’s the code at a smaller scale, in the other it is things like the intended software architecture, processes, tools etc.

In other words, we have to adopt the habit of writing clean documentation. With “clean” I mean complete, correct, understandable and easily accessible. This needs the same kind of discipline we need to write and maintain clean code.

It’s part of every task

Writing documentation is not a separate task of its own. It also should not be an individual step in our workflow, although many issue trackers would handle it that way. Instead, documentation is to be written as soon as it is needed. We should update it as soon as it gets out of sync with its subject matter.

Much of our documentation is related to our code, build scripts, tools, development environment or other things that contain artifacts under version control. Changes to that kind of documentation ideally should be checked in together with the changes to the documented artifact, not after.

This also means that the review of our tasks should not only cover the code, but also the documentation. In addition, even tasks that don’t entail changes to the code base might need a review step in the workflow to review the documentation.

Maintainable documentation

In order to have maintainable project surroundings through clean documentation, the documentation itself has to be maintainable. That means that many of the clean code core principles like easy readability and simplicity apply to clean documentation as well.

It also means that documentation should be accessible and manageable. Accessibility can be given by having one central point where documentation is stored. In addition, the file format in which it is stored should be supported by any platform the target audience might want to use.

Remember that we want to facilitate the simultaneous changes of artifacts and their documentation. That makes version control the most natural place to put that documentation. The best location inside the VCS is the same repository as the artifact itself. This makes it easier for developers to maintain the documentation alongside the artifact.

To get the best out of version control and the documentation together, we should store the documentation in a plain text format. Plain text formats will also solve the issue of accessibility on different platforms. The minimum tool to view the documentation is a simple editor which should be obtainable everywhere in one form or another.

With plain text documentation checked into our VCS we can for example compare different versions of the repository. Doing so will not only see what has changed in the code. We also see changes in the documentation, which can give us a better picture of the changes over time.

There are several different plain text formats, e.g. HTML and Markup/Markdown. Which one is the right one to use depend much on what we want to do with the documentation, e.g. if we want to further process it.

Inline documentation

There are tools that allow us to write documentation inline alongside our code. One example that can be used in C++ sources is Doxygen, where the documentation is achieved by comments in a special format.

On the one hand, inline documentation puts the documentation as close to the documented artifact as possible, encouraging us to keep it up to date.

On the other hand, it may lead us to format the documentation in a way that is directed by the source code structure, which is not always what we need. One also has to be careful to not overdo the inline documentation, e.g. documenting each and every private implementation detail can considerably slow down the development process.

Further processing plain text documentation

For many plain text formats there are tools that can parse and transform them. For simpler formats like Markdown it is not too hard to write such tools ourselves (I recommend looking for one that does what you need first though).

With those tools we can process the documentation as needed. For example the build server could pull the text documentation of different repositories together to create PDF handbooks for users, HTML knowledgebases for integrators and Wiki pages with API specifications for developers.

A good example for such a documentation processor can be seen on GitHub. If you look at markdown files in a repository, GitHub will automatically parse it and present it as formatted text, unless you explicitly open it in “raw” mode.

 

Conclusion

With clean documentation stored as plain text under version control we get the flexibility, accessibility and maintainability we need. At the same time we are able to manage and process it automatically and obtain many other formats from it.