Re: Documentation Process in an Agile environment

Subject: Re: Documentation Process in an Agile environment
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 17 Apr 2012 18:39:52 -0400

On Tue, 17 Apr 2012 14:36:09 -0400, Dan Goldstein <DGoldstein -at- riveraintech -dot- com> wrote:

Good lord, neither one! With both Agile and Waterfall, you can make
significant changes to your original plan as you go along, often at
relatively little cost.

We were accused of doing what you might call "Agile building plans" when we had our house built fifteen years ago. We got the builder's proposed plan, made a few modifications, got the revised version, and approved it. READY TO START CONSTRUCTION, RIGHT?

NO!! Next, the builder prepared the actual plan, which looked much more like the original plan. In particular, all doorways that he been off-center (by our choice) on certain rooms and closets were now centered again. We somehow got to see that plan, and we protested. The kitchen plan was totally unlike what my wife had requested and approved.

So we went back and forth several times trying to get the plans returned to what we originally approved. We were told that we were being a lot of trouble and delaying the construction because we changed our minds so often.

Finally the house was built. BUT TO WHICH PLAN? Well, there was one kitchen cabinet that was inaccessible. The door to it opened into a place that did not access the cabinet's inside! Only one closet had the desired off-center door allowing construction of shelves on the side of the closet. To this day the construction of the kitchen causes my wife to make bad remarks about builders. Also, they never finished the attic like they were supposed to.

NOW BACK TO DOCUMENTATION... Only a brief time before we had that house built, the company where I worked published the XXX User's Guide. Customers later sent in bug reports that the book had errors in it. What were the errors? Features that we had documented HAD BEEN REMOVED from the product as shipped! Customers began asking for versions of the book that correctly supported the product. Internal to the company, the fault was held to be poor documentation.

At the time of both those situations the term "Agile" had probably not been invented, but it sure was being applied, and with lousy consequences for the end users.

Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

RE: Documentation Process in an Agile environment: From: Dan Goldstein

Previous by Author: Re: i.e. vs e.g.
Next by Author: Re: Clashing Initialisms
Previous by Thread: RE: Documentation Process in an Agile environment
Next by Thread: RE: Documentation Process in an Agile environment

What this post helpful? Share it with friends and colleagues:

Sponsored Ads