We all know we should be documenting customer requirements. But what is the best way to do so? Given its popularity, MS Word seems to be the most practical documentation tool to choose. Everybody knows how to use it and it is installed on most computers. For that reason, Microsoft Word has also been my choice for documenting requirements.
The challenge
For a proper requirement specification, you need more than just a few paragraphs, some fancy styling and a few headlines. Because traceability is such a key issue when working with requirements, you also want to be able to clearly reference requirements in the document. I’m talking about some kind of numbering, where each requirement is being assigned a unique number by which it can be referenced across the document (and outside the Word document).
This numbering of requirements is not so easy to achieve with Microsoft Word. In particular, referencing a requirement within the document requires some more technical wizard work than just what is offered to end users.
One of the things I needed was a “link” between customer requirements and product requirements, the latter describing the technical implementation of a customer requirement. And of course, the numbering had to stay consistent and had to update automatically, even when I added a new requirement.
The solution: A Requirement Specification With Requirements Numbering For Word
Together with a developer, we created a requirement specification template for Word that provided it all: automatic requirements numbering, traceability of requirements and customer and product requirements referencing each other.
Template Features:
- professional requirement specification template
- automatic requirements numbering
- create table of contents with customer requirements
- add corresponding product requirement to describe the steps required for the technical realization of the requirement
- customer requirements and product requirements can be “linked” via numbering logic
- standard MS Word file with macro (file format: DOCM). For Windows and Mac.
How to use the template (it’s easy)
Here are the steps that you would typically follow:
Adding a customer requirement
To add a new requirement, first enter a description:
Then choose the style to turn it into a numbered requirement:
The customer requirement now appears with prefix [CustReq x] where x is a running number automatically assigned by Word. Counting starts at 1, and the number will automatically update if you add a requirement before this one.
Add a corresponding product requirement
I like to combine business requirements and a description of their technical implementation (the so-called “product requirements”) in a single file.
This makes traceability of requirements just so much easier. I can just click on the customer requirement, and will be taken to the section in the document that describes what needs to be done technically to implement the customer requirement.
To add a product requirement, run the macro AddReference. This macro is included in the requirements template.
You will be asked for the customer requirement that the new product requirement is supposed to refer to. In this example, I will document the technical implementation for requirement #1.
Choose the customer requirement and press Add Reference.
Now, the product requirement shortcode is shown. I will add a description for the production requirement, and just below the shortcode I can elaborate on the technical steps that are necessary to provide the customer requirement:
What is really nice: The customer requirement and product requirement are linked via a reference. If you click on the product requirement #1, you will be taken to the corresponding customer requirement #1 (both have the same number — this is ensured by the template):
Creating table of contents
You can create tables of content which list out all customer requirements or product requirements. This can be done using the standard TOC feature of Microsoft Word. You just have to choose the style (Customer requirement and Product requirement, respectively) and Word will automatically generate the table of contents.
The result will look like this:
