What are some problems with documentation?

* It goes stale quickly.
* Need to update for every new version of the product.
* The same information is in multiple places, which is a pain to maintain.
* It's not comprehensive enough to cover every single use of the program.
* Nobody uses it because of above reasons.

What if you had a system that could hold all of the documentation and specification elements on your project in one place with no redundency? Then that system could generate documentation automatically, piecing together the elements it needs for a specific document type.

You have a hierarchy of documentation elements, where an element is a piece of a document relating to one feature or part of a feature depending on the level you are looking at.

At the top is functional spec elements, plain english explanations of how the software works and grouped by feature (use case). From these the technical spec elements are made, specifying how the software will be implemented to satisfy the functional spec.

To test the software to make sure it does what you want it to, acceptance tests are made based on the functional spec elements. You can look at any given test and track it all the way back to a specific feature, and a specific use case variant of that feature.

When a bug in the software is found, you can go into the system to check to make sure it's actually a bug by checking against the feature specification elements. That way you don't have to check with three different people to verify it is one, or even worse search through the stack of story cards.

Each element would also need to be tracked through different versions of the product. When is the feature introduced? modified? removed? A good system could keep track of all of the versioning, and produce a document for any given version of the product.

Sounds like a lot of work to use a system like this, doesn't it? We already do this, we just do it in our heads. Extreme programming actually advocates not writing documentation like this because of how involved it can be the old way -- writing documents for each release and keeping track of changes. It is a lot of manual grunt work to write documents, format them properly, etc.

If you had a system to manage the hierarchy of pieces properly (like a defect management system manages defects), it would be easier. It would also keep people on the same page a lot better! It would facilitate communication just like a defect management system does.

In fact, I think a system like this could be used by a manager just watching the programmers do extreme programming -- it wouldn't have to interrupt the programmers necessarily, but it could become part of the checkin process. As stories are defined and completed they are entered into the system along with a list of the tests that verify them.