Self-documenting Architecture

For a software architect, and someone who tinkers with words, this is perhaps an odd thing to say, but it is true: I hate documentation.

I hate it because it is laborious, very often serves no purpose other than to have been produced, and rapidly gets out of date. I have followed methodologies where every UML model under the sun is produced, code is generated, and round-trip engineering is attempted. It never really worked.

But documentation can add value. Code is a very low-level, cumbersome way to get to grips with a system, even if it is allegedly "self-documenting". A few high-level component or sequence diagrams can add a lot of value. Documentation helps you to navigate a system, and understand why something was built.

So what to do?

I think the first thing to do is to distinguish between transient and permanent documentation.

Transient documentation is correct at a point in time, and very often only exists on paper or a whiteboard. It serves to help discuss a solution, but has a very short life span. After it has served a purpose, it usually gets to rest in peace in some archive (or dustbin).

Permanent documentation, however, continues to exist alongside the system, a living description that helps newcomers to understand what was built, and more importantly, why. But permanent documentation needs to be owned and managed. And being managed, needs to be kept up to date. This means that if a project impacts the system, the owner(s) of the permanent documentation of that system need to be notified, so that the documentation can be updated. Of course this is costly, so you do it only to documents you care about.

But this is not the end of the story. Generating navigable documentation from your systems is a powerful way of supplementing your useful formal documentation.

For example:

• using automated API documentation tools like Swagger to generate callable REST service interface documentation.
• using deployment scripts to publish deployment information to a configuration management database.
• using application performance monitoring technology like AppDynamics to show system deployments and interactions.
• using standardised logging and log aggregation (operational intelligence) tools like Splunk to help trace message flows through systems.

Some of these tools cost money, but there are usually decent open source options available, and anyway, if they save you using MS Word, it will be worth every penny.

P.S. I love wikis - they are great for collaborating, but their ease of use means that they are most often cluttered with half-baked attempts at documentation that, at best, offer no value, at worst, offer misinformation. Permanent documentation needs better controls and rigour than a wiki encourages.