Pre or Post Documentation, Which do you Prefer?

27274 Views
4 Comments
12 Likes

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.

Pre or Post Documentation, Which do you Prefer? 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.

Like this article:
  12 members liked this article
27274 Views
4 Comments
12 Likes

COMMENTS

Chris posted on Friday, May 23, 2014 1:43 AM
Tim, a great article.

May I suggest an addition to Bryce's law:

“No amount of elegant programming, technology or methodology will solve a problem if it is improperly specified or understood to begin with.”

I recommend that you invest in some fireproof underwear as the Agilistas are probably, even as I write, gathering their faggots (English sense of the word), matches and a stake and making for your home!
FrattonChris
Tim Bryce posted on Tuesday, May 27, 2014 9:45 AM
@FrattonChris -
Thanks for your note. This will not be the first (or last) time I've disagreed with the software world.

All the Best,
Tim Bryce
timbryce.com
timbryce
Reidmanchester posted on Sunday, June 8, 2014 12:36 PM
I can imagine a BA would press hard for pre-documentation and some developers would press for post doc. However, i find that often some developers don't even read the requirements, instead choosing to imagine what the stakeholders want!
reidmanchester
Only registered users may post comments.

 



Upcoming Live Webinars

 




Copyright 2006-2024 by Modern Analyst Media LLC