The most important thing I can stress here is that I truly believe in the value of good documentation and that this article only addresses what I believe is a flaw in some documentation strategies.
Usually a software document begins its life as an accurate description of what a system is doing and how it’s doing it. As the software evolves, the documentation doesn’t always evolve with it and sometimes in fact the divergence between what the software does and what the documentation says it does, becomes a problem. Now I know in theory that documents should be maintained but the reality is that this doesn’t always happen… In a perfect world software would be right first time and every time and requirements would never change, sadly this isn’t a perfect would.
Before we get smug about it, this problem isn’t limited to the software industry I recently tried changing a taillight on my sisters’ car. Since I had never done this on such a new vehicle I decided to use the manual. The manual never mentioned an extra sneaky little nut hidden in the boot that held the enclosure in place. Sadly I used a Brute Force attack which resulted in a trip to the scrap yard for a new taillight …..
In hind sight I can see what happened; boffin engineers designed and documented the perfect taillight enclosure. After a couple roll tests the perfect taillight flew over the ditch, the boffin engineer’s now added the extra sneaky little nut to keep the perfect taillight in place but never updated the now imperfect manual.
So what went wrong, how can something which should be pretty easy to maintain end up costing me, the user, time and money? …. In my honest opinion it’s as a result of the detailed documentation not residing in the right place.
Using my taillight incident for comparison lets explain what I mean by this in terms of software documentation.
The manual can be compared in this case to a Design Specification, the first paragraph that tells me that the car has a taillight which resides at the rear and has a bulb which is red; this can be described as the Functional Specification. In this scenario let’s compare the instructions on changing the bulb to the Technical Specification.
I’ve found that Technical Specifications often contain overly detailed descriptions of code including the actual code … now look at the source code its lucky if it gets a most basic comment. Years down the road and our code has drastically changed, high level business rules haven’t really changed a lot but our implementation has due to evolving code practices. So now those detailed code descriptions within the documentation are useless if not dangerous, assuming like the boffin engineers we haven’t maintained them.
Back to the taillight… What if the instructions to change the bulb were located in the boot next to the taillight enclosure then someone would have realised that the documentation was out of date. When they added the new sneaky little nut they would immediately realise! “Hey this sneaky little nut isn’t in the instructions, this could cause a problem”.
Same with commenting code and having code reside in Technical Specifications. When you change code you usually comment, but will you go back and ensure the Technical Specification doesn’t reference this exact piece of code and more importantly should you?
In conclusion my suggestions with regard to detailed code descriptions are as follows:
1) Do not include code in the Technical Specification unless its there as a sample or to illustrate naming conventions or something along those generic lines.
2) If you want to document business rules against code do so within the code and then if you need to expose this detail to an audience generate documentation from the source code.
