The Product Management Soapbox - Documentation Timing

			Bibliography Successes Feedback	Contents Search Glossary

Documentation Timing

Posted by Randall Becker, Nexbridge Inc., 25-Nov-1999

"The documentation that defines them (the software)" can be somewhat ambiguous. Depending on which way you choose to develop your software, you may find yourself with unexpected specifications. Let me illustrate:

Using the SDLC methodology, there are a whole bunch of tasks leading up to the development of formal specifications of the software. So, for the initial release, we can theoretically compare the specifications to the software and say whether the software conforms for the purpose of doing a "chestnut audit". That applies only to the initial release, probably the "Alpha" release - in common parlance. By this point, our SCM procedures are, arguably, nothing more than a sophisticated backup strategy.

Where things become difficult is after your software (can I say product yet?) has reached your users (SCM is now involved because users demand changes, yes?). Once that happens, you actually have two sets of specifications written by different groups. The first set of specifications is the program spec/detail design/support & maintenance doc, which is maintained by development. That is the one that is usually considered in the question below. It's also the one that very often becomes itself a maintenance nightmare and ends up out of date (in my experience). The second set is the user documentation/on-line help. That's usually maintained by a technical writing group.

Here are the two contentious points:

As far as the user groups are concerned, whether we like it or not, the user documentation represents the specification of what the product does. If it's not in the documentation, or it's wrong in the documentation, the users are still going to have an expectation that it's going to work that way. As a result of this, the user documentation set becomes part of the specification and you need to audit based on this set as well as the program specifications.
Following onto the previous point, there are two philosophies for creating user documents. The first says "write the document as the product 'should' work", while the second says "write the document as the product 'does' work". Both have their merits. I've seen situations where technical writing and development groups have come to blows over which way to go. With that in mind, you need to know how your user documents are created in order to do your audit.

All of this stuff, especially when you're doing an audit if any kind, is tied really closely to your business process, in general, and development processes, specifically. Understanding that the whole point of "Change Management" is to enable change, not to contain it, is essential to developing good processes, including good audit processes. That's going to mean, in the case of this inquiry, understanding how your specification documents are maintained, who maintains them, and how valid they are at any given point in time.