5.6 Documentation Requirement Pattern

Basic Details

Related patterns:	None
Anticipated frequency:	Up to 10 requirements
Pattern classifications:	Pervasive: Maybe

Applicability

Use the documentation requirement pattern to specify that a particular type of documentation needs to be produced.

Discussion

Documentation can be regarded as anything that is written about a system, no matter what form it takes-not just traditional documents. Online help, presentations (in Microsoft PowerPoint, for example) and comments and other annotations in program source code all count as documentation. Some people might dispute whether anything in source code should count as documentation, but the output from utilities like Javadoc-which generates a coherent set of HTML pages about a body of Java software-must certainly count as documentation, and it seems artificial to include some types of annotations of source code but not others.

For the purpose of this requirement pattern, it's also possible to extend the definition of documentation beyond what's written, to include instructional videos, interactive tutorials, and informative material in other media. In an increasingly multimedia age it seems inappropriate to place artificial limits on what counts as documentation in the broad sense.

Content

A requirement for documentation should contain those parts of the following that are appropriate:

The name and/or type of the documentation. What's this sort of document called?
A description of what the documentation is to contain. Go into whatever level of detail is necessary such that any documentation that complies is likely to satisfy you.
The format or medium to use, which can be as precise as necessary (such as a Word 2007 document or HTML 4.0 pages) but preferably left as open as possible (for example, "a document" or "online").
The name of a standard to which this type of documentation must conform, if any (for example, use of company document templates), along with a description of where this standard can be found. This typically applies when a company has internal standards for particular kinds of documentation. Also explain the extent to which adherence to the standard is mandated (if relevant).
The language the documentation is to be written in, if this is not obvious. In some cases, it might be necessary to state the dialect to use, too (for example, for English, whether it should be British, American, Australian, or some other kind). For a multilingual system, some documentation might need to be provided in multiple languages, in which case those languages must be explicitly identified.

Template(s)

Open table as spreadsheet

Summary	Definition
«Document type name»	There shall be a «Document type name» that contains «Document description». [It shall be in the form of «Document format or medium».] [It shall comply with the «Document standard name».] [It shall be written in the «Language name» language.]

Example(s)

Here are representative requirements for several common (and one or two uncommon) types of documentation. The mention of a type of documentation here is not a suggestion that it should be produced for every system.

Open table as spreadsheet

Summary	Definition
Online help	There shall be online help for every online function in the system. Online help for functions available to customers shall be aimed at them; online help for other functions shall be aimed at internal users. For each function, the online help shall describe how to use that function, such that an uninformed user of average intelligence shall be able to use it as intended.
User guide	There shall be a user guide for all functions available to internal users. The online help could form the basis for satisfying this requirement if it can be consolidated into an attractive printable form.
Operating instructions	There shall be operating instructions that explain to an operator (system administrator) how to run the system. It shall cover at least startup, shutdown, and the monitoring of the system's health.
Procedures manual	There shall be written operational procedures for all business processes that involve use of the system.
Security procedures manual	There shall be written security procedures for the system. It shall, at a minimum, include instructions and advice on the choosing, changing, and protection of user passwords.
Error message explanations	There shall be a set of explanations of error messages. It shall contain an explanation of the meaning of each error message that satisfies any of the following criteria: An intelligent but inexperienced user could not deduce the full meaning. The error indicates a severe problem. There is more to explain about the error. Where appropriate, each explanation shall also describe how to correct or otherwise respond to the message, and (if possible) identify the system component in which the error originated.
Installation instructions	There shall be installation instructions covering each step necessary to install the system.
Upgrade instructions	There shall be instructions for each version of the system to describe each step necessary to upgrade from a previous version of the system.
System design	The design of the system shall be documented.
Javadocs or equivalent	Every Java source file shall contain meaningful Javadoc annotations for every class, interface, method, and public variable. Every source file written in a programming language for which a utility equivalent to Javadoc is freely available shall contain equivalent annotations.
Commenting of source code	All source code shall be commented to a professional standard, sufficient to permit maintenance by a developer other than its author.

Extra Requirements

A documentation requirement is usually self-contained. There are the following rare cases when extra requirements might be needed:

If special software must be written to support the documentation, specify requirements for that software.
If the system's software must be written in such a way as to facilitate a special kind of documentation, specify requirements for what the software must do. An example might be special software hooks to drive an interactive tutorial. Unless you find a dedicated product to help you do it, this kind of thing is very exotic and to be undertaken only if you really know what you're doing. Writing a requirement that says "There shall be an interactive tutorial" is not adequate by itself; you need to provide a better idea of how extensive and how fancy it needs to be-for which extra requirements are necessary.

If you are outsourcing the development of your system, you might want to insist on being able to tailor its documentation. This is especially true for online help, user guide, and other instructional material-although you might as well insist on it for everything except material within source code. Here's an example:

Open table as spreadsheet

Summary	Definition
Documentation tailorable by «Our company name»	It shall be possible for «Our company name» to modify any piece of documentation written for the system, except that residing inside program source code.

Considerations for Development

The development team's biggest interest in complying with documentation requirements is in producing whatever is expected of them. When reviewing documentation requirements, check that those demands aren't unreasonable.

It is, of course, good practice to comment source code when writing it. It's also very helpful to the whole development team to make good use of tools that generate source code-based documentation (such as Javadoc) and to generate it for the whole system regularly as a matter of course (say, whenever a build of all the software is performed).

Considerations for Testing

For the purposes of testing, we can divide documentation into four types, each of which needs to be tested in a different way:

Traditional This means the sort you can print out and read anywhere. Test by reading it and checking its accuracy and completeness. Non-interactive instructional material using other media (principally video and/or audio) can be regarded as falling into this category, in the sense that testing it involves scrutinizing it from start to finish.
Online Test help pages by calling up the help page associated with each function and checking it for helpfulness and for compatibility with the function to which it relates. If there is a requirement that says every online function must have help, you need to invoke every function to check compliance.
Within source code It's better to give developers responsibility for source code quality, including commenting, through peer reviews (though in some organizations testers also participate in code reviews). But if testers are asked to check that a requirement in this area is satisfied, it's not necessary to expect them to verify the quality of comments and other annotations in source code. If they exist and appear to be coherent, that's good enough evidence that developers are taking the trouble to properly document their source code.
Interactive Any form of documentation that permits the user to interact with it (such as tutorials) means you have to devise a set of paths through it to exercise all options at each decision point. This can be a major undertaking.

Also test that all documentation complies with any accessibility requirements. See the accessibility requirement pattern in Chapter 8.