In addition to my essays, I have written a considerable amount of documentation for business and systems over the years; everything from Policy Manuals and proposals, to Feasibility Studies, Systems Documentation, Test Plans, software specifications, User Manuals, and Audits for systems and projects. I find such work relatively easy, but I am always amazed by those clients who really do not grasp the significance of technical documentation. It is not uncommon to be asked to come in afterwards and provide a description of the newly created system and software. This is considered post-documentation whereby you test the system to see what it is capable of doing, and writing the supporting documentation. I have always considered post-documentation to be backwards. It is analogous to asking an architect to draw the blueprints of a skyscraper after it has been built. In other words, I’m a proponent of pre-documentation whereby flowcharts and text are used to record design decisions in the same manner as architects and engineers, in layers whereby you go top-down from the general to the specific. Under this approach, your documentation is completed before programmers begin to write the source code. The same is true where the architect finishes the blueprints before digging the first shovel of dirt. Call me old-fashioned, but I have never seen this approach fail. Some programmers consider documentation a waste of time (see “Agile programming”), even going so far as to claim it is detrimental to productivity. Instead of getting all the software specifications recorded on paper at the start, they prefer to begin hacking on the program code and keep modifying it until the end-user is satisfied. Someone is then called in to figure out what the software does and write the documentation (post-doc). Imagine two separate software project teams given the same assignment, one uses a pre-documentation approach, the other post-documentation. From start-to-end, which team do you believe will finish first? The pre-doc group will seem to take considerable time up-front documenting the specifications. However, the programmers should spend nominal time interpreting the specs and writing the programs. When the programming is done, the project is done as the documentation was completed beforehand. In contrast, the post-doc group will begin programming almost immediately. Yet, because the specifications were incomplete and fraught with misinterpretations, they will inevitably have to rewrite the programs over and over again until they produce something remotely usable to the customer. Finally, they call in someone to write the documentation. Obviously, the post-doc approach represents a more costly expenditure requiring more time to complete. Programmers appreciate the need for documentation but rationalize, “We do not have time to do it right.” Translation: “We have plenty of time to do it wrong.” Consequently, they abhor the concept of documentation in any form and resist any and all attempts for them to produce it. The one axiom programmers cannot deny is, “Good specifications will always improve programmer productivity far better than any programming tool or technique.” I guess I should be thankful for those embracing post-documentation. If everyone was doing it properly, I wouldn't have too many technical writing opportunities.
“No amount of elegant programming or technology will solve a problem if it is improperly specified or understood to begin with.” - Bryce’s Law
Keep the Faith!
Author: Tim Bryce Note: All trademarks both marked and unmarked belong to their respective companies. For Tim’s columns, see: timbryce.com Copyright © 2014 by Tim Bryce. All rights reserved.
brought to you by enabling practitioners & organizations to achieve their goals using:
enabling practitioners & organizations to achieve their goals using: