Documenting the Dinosaur
Imagine you are seated in a class room. The blackboard reads ‘Aerodynamics 101’. The lecturer is a elderly bespectacled gentleman with an air of excitement about him. As he welcomes you to his course, he shares that he is about to illustrate the mechanics of flight. On his table you notice an over-sized model of an aeroplane.
Barely containing your excitement, you open your notebook eager to make notes. The lecturer proceeds to point to different parts of the plane and explains what they do. He goes into fair bit of detail about the aerodynamic characteristics of each such as mass, turbulence etc. After this fairly lengthy exposition, he completes describing the last part of the model aeroplane’s anatomy and concludes that by now you must be having a fairly good understanding of aerodynamics. Before you open your mouth in protest, the bell rings indicating the end of the allotted time for the class.
Before you wonder, how such a class can be of any benefit at all to a student of Aerodynamics, notice that this analogy is perfectly applicable to Technical Documentation. Most of the time a code base is handed over with documentation that describes in a fair bit of detail about its various moving (and non-moving) parts. There is considerable amount of information lacking about how the system came to be what it looks like today.
Any sufficiently complicated system is a result of many design decisions, trade-offs and optimisations. The complexity cannot be appreciated unless we describe the reasons that led the creators to such decisions. This provides the vital aspect of Context to the system we have at hand.
A typical system’s documentation is spread over several documents such as Design documents, Technical specifications, User manuals to even the code and unit-tests themselves. Barring a few exceptions, these documents would talk about the end-state the system is in today. Perhaps, digging through the version control system might provide some insights, but generally the Context is buried for convenience.
This leads several serious problems ranging from duplication of effort to even failed integration efforts. At one of our banking clients, we once tried to implement an ambitious initiative i.e. a project to add sequencing to all internal intra-company messages. This involved wrapping a header around the existing messages which would now be called payload. The header would contain timestamps and serial numbers which would help in resolving the correct sequence (for the uninitiated, this is actually a pretty hard problem).
Half way into design we realised that the existing messages did contain a fairly unused field named UID. It was, in fact, derived from the message creation timestamp. They appeared in a strange but a deterministic sequence. This was previously considered to be a randomly generated number! Not only was the entire exercise scrapped, we gained smadmiration for the designers of the legacy system.
What’s the real test of good documentation?
We all fall into the trap of Documenting the Dinosaur. Without understanding the evolutionary steps behind the creature, it would be impossible to appreciate its current form. Of course, the best way to resolve this is to compress all the historical decision points into the design documents. In fact, some document authors actually do this.
But this is a laborious exercise. There are various other means to verify the effectiveness of the documentation:
- Extensibility: How easily can one integrate with the existing system? How many times have such attempts failed?
- Sustenance: How actively are the documents maintained? How much of context is carried over when a change is implemented?
- Ownership: Are the designers/developers/users of the system in joint ownership of the documents? If the documentation work is performed by a separate team, are there means to avoid it?
- Collaboration: How easy is it to view and change the documentation? Is it open for public review?
A positive answers to these key questions can prove to a critical checklist to your documentation. At worst, it may be a bit of additional work, but it can certainly prevent your system go the way of the Dinosaur!
