Question re: managing document changes as software changes occur?

Subject: Question re: managing document changes as software changes occur?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Laura Johnson <lcjohnson -at- cfsloans -dot- com>
Date: Sat, 15 Apr 2006 10:09:30 -0400

Laura Johnson wonders: <<I've been tasked with coming up with a process that makes sure that changes made to the software design are reflected in the technical documentation. Meaning, we'll be having a Requirements doc, a Specifications doc, etc., but, as the software design process moves along, change requests come through and the software is changed....but the documentation rarely is.>>

Welcome to life in software development. <g> The key thing is that you seem to have a process in place that uses "change requests" rather than simply random mutation of the software. If you can find a way to receive the change requests, then you will be every bit as aware of the status of the software as the developers are. When something changes, add it to your list of things to check against the documentation.

Of course, first you have to get the documentation up to date:

<<What we're dealing with here is an application that is now 2 years old and there are literally several thousand change requests that have been implemented...but the documentation never reflected those changes. So when you look at the original documentation, it's almost completely different from the current version of the software. The original documentation is pretty much useless.>>

If that's really the case, then you need to restart your documentation from scratch, and use the old documentation almost exclusively as reference material. That is, you can use it to research how something was once supposed to work, and use that knowledge to provide insights into how it currently works--or at least to serve as the basis for informed queries to the developers. Some of the interface won't have changed, so you can copy and reuse that original documentation.

One slightly more efficient way to work is to find out what aspects of the software have been frozen semi-permanently, which ones will soon be frozen, and which ones are still being "made up as we go". The more frozen the module, the more effort you should devote to documenting it. There's little point documenting something that you'll have to change daily, but a lot of value in documenting something that won't change much.

Inform the development manager that the documentation will be ready 2 weeks after the final interface freeze--with "2 weeks" being replaced by the time that will actually be required for you to do a final run-through of the documentation so that you can check every line against the software to detect changes that slipped through the process.

<<but we're starting to develop a new application so they want me to put something in place so things don't get out of control again.>>

Two useful references are Alan Cooper's book "The Inmates are Running the Asylum" and his Web site ( The correct way to design software is to spend a lot of time up front prototyping the software interface based on the problems you're trying to solve for its users. It makes no sense to actually start coding before you know what you're trying to achieve. While you do this, have the developers devoting some skull sweat to the thorny algorithms they'll need to develop to solve those problems (i.e. so you aren't wasting their time while you plan).

It's important to note that interfaces take hours to develop, whereas algorithms (the plumbing below the interface) takes days or weeks to develop and troubleshoot. Solve the interface first, and you can begin documenting it because it won't have to change much, if at all. The plumbing can evolve a hundred times, if necessary, but if the interface is stable, you can keep working while the plumbers plumb.

The objection that's often raised is that nobody works this way, or that it's impossible to foresee all eventualities. Remind them that architects and engineers have worked this way for (respectively) millennia and centuries for one reason: it works better than simply figuring out the design as you build something. Programmers sometimes like to put on airs and proclaim how mystical their work is. Nonsense. There's certainly an art to solving programming problems, but programming is as rigorous an activity as engineering, and a good half of the problems we face in using software result from programmers who wave their hands and make airy statements instead of buckling down to do the hard work.

Here's the hard part: Once you have a functional and effective design, you stick to it. No matter how many cool ideas you come up with along the way, you resist the temptation to implement them in the current version of the software unless they're crucial for the current version to work.

New features are what new releases are for. If the managers balk, remind them that new releases represent an ongoing series of income opportunities for the company, whereas trying to cram every imaginable feature into the current version represents nothing more than an ongoing series of bug fixes. Ask them which is better for the bottom line and their career. They'll get the hint.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

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

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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

Question re: managing document changes as software changes occur: From: Laura Johnson

Previous by Author: Friday fun (one day late): Oh, really?
Next by Author: Goodbye Z-pattern; hello F-pattern?
Previous by Thread: Question re: managing document changes as software changes occur
Next by Thread: Re: Question re: managing document changes as software changes occur

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

Sponsored Ads