Creating the Body of the Document
Once the research and interviewing has been completed, begin to assemble the body of the document. The author cautions about using a "write as you go" method, conducting research for one section, then writing that section, then moving along to the next section. IT may seem to be more "productive" because you're producing written material, but that approach will require a great deal more revision time (or alternately, people will feel "married" to what is written and be reluctant to change it, even if changes are needed).
Documenting the Current State
There is some debate over whether documenting current state is worthwhile, as it doesn't' relate to the project at hand. The author si in favor of it, because it provides a starting point, allows the "future state" section to avoid discussion of status quo, and helps to ensure that nothing important is overlooked when designing the new system.
The basic approach is to sort the information you have gathered from the stakeholders to differentiate what describes the current system from the things they want and need in the future system, then organize the information into the sequence of steps.
Next, develop a draft diagram that explains, at a high level, what the current state is and present this to the team to determine whether it is accurate. Often, this will elicit other information that was neglected in the original description, and may result in additional ideas for future state.
In addition to the system itself, consider the context in which it operates: the sources of all data that serves as input, the destination of all data that is output. Be especially wary of instances in which other systems are involved (is the process really a separate one, or part of the one you'll be replacing).
Remember also that a system is a group of processes. Document each process individually, including the ones that do not seem to be relevant to the project.
Describe the present state in the same terms, and by the same structure, as future state. This will facilitate comparison.
Writing the Future State
The future state is less a matter of researching and documenting as it is an act of writing, in that you are describing a hypothetical future. It can be done by much the same methods as documenting current state, though there are a few unique issues:
Rather than rewriting the requirements that were already stated in the current state documentation, create a separate section that lists requirements that will be carried forward, and reference what is already written.
Beware of the desire to design the solution. The main difference is that a requirement indicates "what happens" but does not get into the details of how it will happen. For example, "user chooses new account from the file menu" crosses the line - it should be "user initiates the process to create a new account" without details of how that's done. Another example: "customer address should be retrieved from the marketing database" crosses the line - it should be "customer address should be retrieved from existing records."
The author then contradicts this, to suggest that providing granular details (what database would be used) can be done when it is "essentially predetermined" and makes it easier for the audience to understand the documentation. He then says there is a separate document (the functional specification) that should provide these details.
Checking for Completeness
There is no reliable way to ensure that every requirement has been captured, and you should be wary of expending too much effort hunting down loose threads. Even so, there are a few techniques that can help to catch any glaring omissions.
The author suggests creating data flow diagrams, even if they are not necessary to illustrate the report, as a way to identify "holes" in the requirements. Look at the inputs and outputs of all processes, particularly, to determine what might be missing.
Having the document reviewed by the stakeholders and developers can help identify omissions that are of particular concern (to each of them).
Developing prototypes that mock up functionality for specific scenarios can help to identify missing elements. They can be PowerPoint slides or mock interfaces with some functionality. Have individuals who will use the system review the prototype to identify missing pieces.
Reference Material
Shunting detailed information to appendices rather than documenting it as part of the system description can de-clutter your documentation, but it should still be available for those who get hung up on details. In some instances, it may not be necessary to include this material with the documentation at all (refer to its existence elsewhere), though whether to exclude or include is a matter of judgment.
Gap Analysis
The Gap analysis makes reference to difference between current and future states. The author suggests that, if you've been thorough in your documentation, this will practically write itself: Use a three-column table that shows the current requirement, new requirement, and the reason for the change (generally, a benefit to be gained)
Requirements Summaries
The requirement summary extracts detailed information and presents it in a list format. It should be organized in the same order as the documentation, and requirements should be numbered to facilitate reference.
Data Specifications
Data specifications are a vital part of the document, though they definitely belong in an appendix. Use a four-column tabular format, which specifies the following for each datum:
- Name - The name by which it is referred to in the documentation (not necessarily variable name in code)
- Description - A brief, nontechnical description (e.g.: "the date on which a payment is received" or "an amount in US currency"
- Derivation - How the datum is derived. It may be manually entered, it may be retrieved from a file or database, or it may be calculated on the fly (e.g. "due date is billing date plus 15 days")
- Source - Indicates the place that the data resides (name of database, table, field, etc.).
Report Specifications
Where reports are generated, it can be helpful to show examples of reports, either using dummy data or place holders, to show the design. Since reports are often received/reviewed by management, it is a topic of keen interest.