The more detailed is your initial documentation, the bigger the risk that the document (or parts of it) will be obsolete by the time the systems goes into production. Requirements and priorities change, things that everybody thought would be easy to implement turn out to be unfeasible (requiring workarounds), etc.

The best time to write system documentation is post implementation, when it’s possible to document the system as it was actually designed and executed, not as planned and specified.

Back to Doug’s question, my documentation is typically composed of a high-level overview of requirements accompanied by diverse representations, such as use cases, annotated wireframes, illustrations of categories (e.g., “sales representative” and “engineer” are categories of a more general concept “employee”). The types of document produced vary from project to project, but the constant is that each document I produce is based on someone (either a stakeholder or someone from the project team – developer, tester, etc.) confirming that the document is useful to them.

If someone tells me they will use it, no matter how redundant it appears to be (e.g., a textual description of exactly the same thing I depicted in a class diagram, for a stakeholder unfamiliar with UML to be able to read), I’ll produce it.

I found your question very interesting, since recently, in the context of my current project, I had a chance to give this subject some thought.

The value of proper requirements documentation upfront is that if it is done right, it is the product of good analysis of stakeholder needs. This in turn should result in better inputs into the design and development processes, i.e. proper context for the requirements, identification of the areas where designer or developer has relative freedom in what their solution looks like and where they are more constrained by the stakeholder requirements.

I agree that a massive requirements document, even if it is a product of rigorous and high-quality analysis is often essentially unusable. Different stakeholders have different “need-to-know” needs and putting everything into a single source of documentation has the tower of Babel effect.

My favored approach is for documentation to match phases of the analysis, where one goes from defining the big picture outlines of the solution to nailing down the detailed requirements. So instead of a large tome, there are several smaller documents targeted to provide the necessary information for each stakeholder type. Without reference to specific methods, let’s say there are 3 levels of analysis and therefore documentation.

First level is to document the broad characteristics of the solution – definition of the problem and its scope, approach to solution, major problem areas addressed, etc.

The second level of analysis is to identify the business processes impacted by the proposed solution and to define those impacts; to identify the major pieces of functionality and describe what they will do to meet the stakeholder needs. The level of detail on this analysis level depends on project particulars, but it should not go down the rabbit hole of individual requirement level of detail. It is the solution’s context and it should give readers the idea of what the entire thing looks like. Finally, the documentation for this level of analysis serves as a table of contents for the rest of the documentation. Thus, given the context, stakeholders can pick and choose business processes or features in which they have interest.

The third level of analysis is at the requirements level, centered around specific business processes or significant areas of functionality.

What I like about this arrangement is that it gives the stakeholders the ability to filter out the “noise”, i.e. specific things that have no direct impact on them, and focus on a smaller sub-set of documentation they must understand. I see some segments of the audience never getting to the 3rd level. I see some segments for whom 1st level is not much use. However, as a whole, you get reasonably close to a properly informed set of stakeholders. I have used this approach and I find the results promising.

Finally, regardless of the size of the requirements documentation, whether it is a large tome or many smaller documents, documentation is all about communication, and the same principles apply – simple unambiguous messages, communication channel free of extraneous noise, etc. A well-laid out and well-written document, no matter the size, has the most value. I have seen cases where a small document is incomprehensible, and a large document with loads of detail is very easy to understand.

Hope you find my contribution helpful.

Thanks so much for your comments and suggestions. As you know this is a fairly controversial topic when discussing the transition to a new state of documentation and there is much to consider.

Bridging-the-Gap’s readers will surely benefit from your intelligent contributions

Doug

It could be at the point where you have produced an early prototype based on the outline requirements. That prototype can be used to derive the detailed requirements and build the final product. If there’s going to be just the one split then the second one would probably be better.