Low level aka detailed design documentation has been an interesting point of debate. We range from the agile manifesto which states focus should be on working code over documentation and people using this as an argument for not producing documentation. On the other end of the spectrum as someone working for a large SI, documentation is more often than not contractually binding and accurate docs are key when taking work from a different supplier organization.

It is clear that documentation is an essential element. But I do agree with the agile manifesto, a business operates on its software, not documents, although the docs help us keep the software maintained and running.

How do we balance the age-old conflicts of …

• Documents get out of date because they are kept separate from the implementation
• Documents, particularly when rushed don’t provide the information necessary
• Document templates having sections used a tickboxes rather than guide rails
• Making sure we’re working with the most upto date document

Possibilities

One of the key issues for documents getting out of date is a compound issue of accessibility, visibility and ease of maintenance. These compound to separate the documentation from the reality of code and configuration.

This can be eased by bringing documentation to being ‘physically’ closer to the code as we often see with readme markdown files on GitHub for example. But we can get closer with quality code commenting, particularly for each package and module. Just about every code or notation format had its own document generator from well-proven Javadoc to Terradoc for Terraform. To illustrate my point here are a couple of examples:

• https://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html
• https://ruby-doc.org/stdlib-3.0.3/libdoc/observer/rdoc/Observable.html

If done well the documentation can be generated and deliver the right information. It would mean in structured change management the change task for the code includes the documentation. The ideas behind combining code and documentation can be seen with good API Blueprints.

When you still need to produce publishable documents, you have the opportunity to stitch multiple class and package generated docs together using tools such as pandoc. Arguably it would be the developer’s job to establish the pandoc configuration file (Documentation as Code).

You can add to this if done carefully, by adding diagrams such as UML representations. Importantly this process can generate representations that include lots of detail that would be noise to the key representation (time for tools like Sparx to support annotations that can give hints as to what to show in a generated model).

Pitfalls

The biggest risks of this approach are:

• People paying lip service to documenting code, or using the argument that agile means no documentation (an age old misrepresentation).
• Comments reflect the code correctly
• Assuming the documentation will be clear because it is writte6x n

These pitfalls could be in theory be addressed through some smarts such as comparing the volume documentation generated against the number of lines of code and code complexity metrics.

But like many things, good culture and good application of principles are essential.

Exploring further

There are growing dedicated resources in this space, check out:

• https://idratherbewriting.com/
• https://swimm.io/