THE BRYCE IS RIGHT!

Software for the finest computer – the Mind

  • Tim’s YouTube Channel

  • Enter your email address to follow this blog and receive notifications of new posts by email.

    Join 2,090 other followers


  • "BRYCE's UNCOMMON SENSE SERIES"
    4 New Printed Books & eBooks from Tim on:
    Change/Technology, Management, Politics, and the American Scene
    Click HERE.

  • Categories

  • Fan Page

  • Since 1971:
    "Software for the finest computer - The Mind"

    Follow me on Twitter: @timbryce

    hit counter

     

  • Subscribe

PRE OR POST DOCUMENTATION, WHICH DO YOU PREFER?

Posted by Tim Bryce on May 19, 2014

BRYCE ON SYSTEMS

– Documentation is a working tool and a byproduct of design. – Bryce’s Law

(Click for AUDIO VERSION)
To use this segment in a Radio broadcast or Podcast, send TIM a request.

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!

Note: All trademarks both marked and unmarked belong to their respective companies.

Tim Bryce is a writer and the Managing Director of M&JB Investment Company (M&JB) of Palm Harbor, Florida and has over 30 years of experience in the management consulting field. He can be reached at timb001@phmainstreet.com

For Tim’s columns, see:
timbryce.com

Like the article? TELL A FRIEND.

Copyright © 2014 by Tim Bryce. All rights reserved.

NEXT UP:  EVALUATING EMPLOYEES AND MANAGEMENT – Two valuable forms for evaluating both management and the workers.

LAST TIME:  SCIENTIFIC FLIP-FLOPS  – What is good for us? Scientists really do not know.

Listen to Tim on WJTN-AM (News Talk 1240) “The Town Square” with host John Siggins (Mon, Wed, Fri, 12:30-3:00pm Eastern), and KIT-AM 1280 in Yakima, Washington “The Morning News” with hosts Dave Ettl & Lance Tormey (weekdays. 6:00-9:00am Pacific). Or tune-in to Tim’s channel on YouTube.

Advertisements

7 Responses to “PRE OR POST DOCUMENTATION, WHICH DO YOU PREFER?”

  1. Tim Bryce said

    A K.S. of Oklahoma City, Oklahoma wrote…

    “I totally agree Tim. (or should I say that I pre-agree rather than post agree?)”

    Like

    • Dave boddy said

      Having a career in software engineering I can assure you that documentation is vital. I made my team update their specifications regularly so they were never more that two weeks out of synchronization with the code. Just because its written doesn’t mean it can’t change merely document the whys and wherefores.

      Like

  2. Tim Bryce said

    A J.S. of Phoenix, Arizona wrote…

    “Bryce is right about this one.”

    Like

  3. Bill said

    Re: Post Documentation

    Many times I’d like to strangle the document writer who prepares instructions on how to use software or products. Unfortunately, many of these writers cannot put themselves on the same level as the user. The instructions, outline of steps or pictorials are often ill conceived.

    Like

  4. Tim Bryce said

    Bill – You might find my column on “The Language of Systems” to be useful –
    https://timbryce.com/2012/10/29/the-language-of-systems/

    Like

  5. […] PRE OR POST DOCUMENTATION, WHICH DO YOU PREFER? […]

    Like

  6. Tim Bryce said

    An F.C. of the United Kingdom wrote…

    “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!”

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: