As I mentioned in my post about user stories, Steve McConnell provided excellent arguments for using User Documentation as software requirements documentation in his book “Software Project Survival Guide (Pro -- Best Practices) ”.   I have found that this work very well.

User documentation makes excellent software requirements documentation because it:

• Covers all of the external capabilities of the system
• Has to be kept up-to-date because users see it
• “Hits two birds with one stone” (or ” Two snakes with one stick” in Brazil)

Since the user documentation is intended to explain the entire system to a user, it should logically express all there is to know about the system from the outside.  And, since it goes to paying customers, it is likely to be kept accurate.  This is nice because technical documentation is infamous for being out-of-date.  User documentation is a part of the living ecosystem of the product and those are the important parts to keep.

User scenarios, stories, demos, and tests can all be used to feed the user documentation or vice-versa.

User documentation is usually made after the software is developed.  So developing it first does change the way that a software project runs.  A sincere effort will need to be made to encourage analysts and user documentation writers to work together in advance of a software development effort and it will probably take some dedication and practice.

One important thing to keep in mind is that it is easy to write something into a document that can’t be done in software.  Fantasy books are popular, but software documentation is not the best place for fiction.  For this reason, a software engineer with current experience should be employed to work on the documentation as well.

Like all other forms of specification, you don’t have to wait until the whole document is complete before you start to develop parts of it.  Agile 101 says it is a good idea to start developing the most valuable parts of the product as soon as possible.  This limits the risk of not having enough resources to finish the whole product.  The least valuable parts of the product can often be left for a future release.