Documentation Is a Means to an End

Most requirements artifacts, Vision documents, use cases, and so forth ”and indeed software development artifacts in general, including the code ”require documentation of some kind. Given that these documents divert time and attention from essential coding and testing activities, a reasonable question to ask with respect to each one is "Do we really need to write this document at all?"

You should answer "Yes" only if one or more of these four criteria apply.

1. The document communicates an important understanding or agreement for instances in which simpler verbal communication is either impractical (for example, a larger or more distributed team) or would create too great a project risk (for example, a pacemaker programmer device).

2. The documentation allows new team members to come up to speed more quickly and therefore renders both current and new team members more efficient. ^[2]

   ^[2] In our experience, this issue is often overrated, and the team may be better off focusing new members on the "live" documentation inside the requirements, analysis and design tools, and so forth.

3. Investment in the document has an obvious long- term payoff because it will evolve , be maintained , and persist as an ongoing part of the development, testing, or maintenance activity. Examples include use case and test case artifacts, which can be used repeatedly for regression testing of future releases.

4. Some company, customer, or regulatory standard imposes a requirement for the document.

Before including a specific artifact in your requirements method, your team should ask and answer the following two questions (and no, you needn't document the answers!).

1. Does this document meet one or more of the four criteria above? If not, then skip it.

2. What is the appropriate level of specificity that can be used to satisfy the need?

With this perspective in hand, let's move on to defining a few requirements approaches that can be effective in particular project contexts. We know, of course, that projects are not all the same style and that even individual projects are not homogenous throughout. A single project might have a set of extremely critical requirements or critical subsystems interspersed with a larger number of noncritical requirements or subsystems. Each element would require a different set of methods to manage the incumbent risk. Therefore, a bit of mixing and matching will be required in almost any case, but we can still provide guidelines for choosing among a few key approaches.