Requirements Documentation Standards

We use a set of requirements documentation standards to generate consistency in our writing styles. They should be applied to the documentation produced in the requirements phase of a project, including the requirements, use cases, diagrams and process flows. Instead of writing in individual preferred styles, the entire team writes in the style defined by the standards.

The notion of requirements documentation standards is similar to coding standards for a development team. For development teams, they will have agreed upon conventions such as naming variables without the _ character, making data private and what code comments contain.

Requirements documentation standards can be valuable to a product management team’s overall goals of producing concise, readable, easy to digest, quality requirements. The standards promote consistency in the documentation efforts of a team. When a multi-person team is producing documentation for a customer, the use of standards can result in a multi-author document that appears to have been written by a single person.

Here are a few examples of what I mean by requirements documentation standards:

• Requirements should take the form of “(subject) shall (action verb) (observable result)”. For example, "System shall display a list of all containers of the requested chemical that are currently in the chemical stockroom”.
• Use the words “User” and “System” as subjects in active voice sentences.
• Use case names should be of the format (Perform Action on Object). For example, “Add Item to Cart”. If the same functionality is described in multiple use cases because the actor is different in each, then add “for (actor)" to the end of the use case names.
• Each step in the use case should describe a single, discrete action by the user or the system. Multiple actions should not be combined into a single step.

The consistency gain from standards will improve readability, including how quickly someone can understand what is written. Anyone on the receiving end of the documentation can become familiar with one style, so the time spent reading the documentation will be focused on content rather than learning the author’s language. Similarly, our team has a practice of reviewing each other’s documentation, where similar writing standards across teams can simplify the review process. Writing in similar styles allows someone new to the project context to review the document and focus on the content as opposed to the language choices.

As with code, the original authors of requirements documentation are often not the ones to maintain it throughout the project. Therefore, if written in a consistent style, it will be easier for a new product manager to understand the documentation.

Developing documentations standards can lead to additional benefits to the overall team. The team can work together to develop the standards for a given organization or project. Once the standards are decided, time will not be wasted on silly debates over things like the use of active or passive voice, the number of spaces between sentences or how to name use cases. The more productive suggestion is to have the debate once (or periodically), decide as a team on a standard and move on to implement it.

There are some potential downsides that need to be considered if developing a requirements documentation standard. First, enforcing such standards will take project time, and in fact, they may get ignored in many cases. The benefit that applies to doing internal reviews is that efforts can be focused on reviewing content over language, grammar and format. However, if the standard is not followed, excess time is spent in the review because the document is being reviewed against the standard as well as the content.

Realistically, such standards can create more headaches then they are worth if not done in a pragmatic manner. With this in mind, it is important to realize that standards should not be viewed as immutable. In fact, a given team needs to adapt the standards to what is most appropriate for their project. The project team needs to realize that even if each person makes a “standards” mistake 2% of the time, it is not going to lead to project failure.

The smaller the size of the team, the less important and thorough the standards need to be. For just one person working on a project’s deliverables, there can still be benefits to documentation standards, particularly if the audience is reading other product managers’ documentation (such as for internal team reviews). However, the most important thing in this case is that the individual is consistent within the documents.

There are a few suggestions I can make in developing a standard for requirements documentation. First, develop them as a team, so that the standards are not forced on anyone who is not bought into them. Review them periodically and update as appropriate for the state of the team. Be sure to keep the standards simple and useful, which leads to the most important tip - provide a rationale behind each one. If there is obvious value in each of the standards, they will more likely be followed.