Requirements Traceability with Microsoft Word

Why use Word for Requirements Documentation?

… you might ask. Usually, I strongly encourage our customers to use suitable tools for managing their requirements. There are plenty of reasons why I recommend using professional tools for requirements management, but an important reason is to ensure requirements traceability. For example, of the six sources of RE project failures identified by Michelle Boucher, at least three have to do with traceability.
While we do recommend other tools, Word is available in most companies, documents are easy to exchange, the review mode is pretty good and sometimes using other tools is simply not an option for different reasons. Hence, many people do use Word to create requirements documents. My own experience in using Word for authoring a requirements document is that it seems to work well in the beginning, but as soon as already documented requirements begin to change things start to get nasty. Especially if there is not just one requirements document, but several.

Problems for Requirements Traceability

Two problems I ran into rather quickly when using Word for requirements documentation, and especially requirements traceability, are:

• No reliable automatic numbering of requirements
• No robust requirements traceability (cross referencing of requirements)

For both problems I came up with workarounds that work sufficiently reliablly to use Word for RE, at least in small, short-time requirements projects.

Reliable automatic numbering of requirements

When working with requirements I want to give a unique ID to every requirement. There are many reasons to do this, one is that with a unique id, I can reference this requirement even outside the document. One example for this is to link to requirements in test cases, in a mail or a in a ticketing system. I want this numbering to be automatic, so I don’t need to think about duplicate IDs. The ID should also be rather short, so that IDs don’t clutter the document and I can use them to talk about a particular requirement with a colleague. Finally, the ID should not change, after I assigned the ID to a requirement.

Achieving this with Word is not easy. After googeling for a while, I didn’t find an easy solution that fulfills all the above criteria. Using the automatic numbering of Word won’t work as the numbers are tied to the location in the document and will change, for example, when I delete or move a requirement. The same holds for custom sequence fields (“{SEQ …}”). Using GUIDs à la “bcd2b41e-537d-4e5f-a7ef-8b81cc927b21” is impractical and I didn’t want to do manual numbering in the first place.

What I ended up with is to use a set of macros for this purpose. The allow me to retrieve IDs I can use for numbering my requirements. Each time I retrieve a new ID an internal counter is incremented, so I won’t get any ID twice. Here are the details: The working horses of my macros are two VB routines, UpdateBookmark and GetNewId. UpdateBookmark creates or updates a Word bookmark (which is, basically, a named piece of text) with a certain name. GetNewId uses this routine to retrieve a counter value stored in a certain bookmark and increment the counter. Here are the two routines:

Const COUNTER_BM_NAME = "_req_id_counter"
Sub UpdateBookmark(bookmarkName As String, text As String)	 	 
 Dim BMRange As Range	 	 
 If (Not ActiveDocument.Bookmarks.Exists(bookmarkName)) Then	 	 
   ActiveDocument.Bookmarks.Add bookmarkName	 	 
 End If	 	 
 Set BMRange = ActiveDocument.Bookmarks(bookmarkName).Range	 	 
 BMRange.text = text	 	 
 ActiveDocument.Bookmarks.Add bookmarkName, BMRange	 	 
End Sub	
 	 
Function GetNewID() As String	 	 
 Number = Val(ActiveDocument.Bookmarks(COUNTER_BM_NAME).Range.text)	 	 
 NewNumber = Number + 1	 	 
 UpdateBookmark "_req_id_counter", CStr(NewNumber)	 	 
 GetNewID = CStr(Number)	 	 
End Function	

Now come the actual macros. There are three of them: InitCounter initializes the counter bookmark. It needs to be executed once per document. Alternatively you can just create a template document where the counter bookmark is already created. More interesting is the second macro InsertNewCounter: This macro uses GetNewId to retrieve a new counter and inserts it into the document at the current cursor position. Most useful is the last macro: NewRequirement. It asks for a requirement name and a name for a bookmark and generates a whole requirements title with a new ID. The requirement title contains two bookmarks, one for the requirement ID and one for the whole title. We will use these bookmarks for cross-references later. Here are the three macros in their full beauty:

Sub InitCounter()	 	 
 If (Not ActiveDocument.Bookmarks.Exists(COUNTER_BM_NAME)) Then	 	 
 UpdateBookmark COUNTER_BM_NAME, "1"	 	 
 End If	 	 
End Sub	 	 
	 	 
Sub InsertNewCounter()	 	 
 If (Not ActiveDocument.Bookmarks.Exists(COUNTER_BM_NAME)) Then	 	 
   MsgBox ("Counter not initialized. Run 'InitCounter' Macro first.")	 	 
   Exit Sub	 	 
 End If	 	 
 Number = GetNewID()	 	 
 Selection.TypeText (Number)	 	 
End Sub
	 	 
Sub NewRequirement()	 	 
 Dim RTitle As String, RBookmark As String, RIdBookmark As String	 	 
 RTitle = InputBox("Requirements Title")	 	 
 RBookmark = InputBox("Bookmark Name")	 	 
 RIdBookmark = RBookmark & "_ID"	 	 
 UpdateBookmark RIdBookmark, ""	 	 
 UpdateBookmark RBookmark, " " & RTitle	 	 
 UpdateBookmark RIdBookmark, GetNewID	 	 
End Sub

Let’s see them in action! I put the macros in my Ribbon, so I can access them easily. I first initialize the counter, this prints a little “1” (which I could hide, but for presentation purposes I leave it visible). Now I add two requirements, watch the counter get incremented. Finally I delete the second requirement and add a third one instead. As required, I get again a fresh id. See the screenshot below for the result.

Robust Requirements Traceability

The second problem I stumpled upon is to have a robust way of cross-referencing requirements even across documents. In one of my current projects, requirements are spread across three abstraction levels: User Requirements Specification (URS), System Requirements Specification (SRS) and Architecture Specification (AS). In each document, I reference requirements of the other two documents. When I reference a requirement in URS from SRS (ie. across documents), ideally the reference automatically displays the correct ID and title.  A first approach I tried is using hyperlinks. Although I can directly reference a bookmark in a different word file, I cannot bind the link text to the bookmark’s content. That means, when the title of the original requirement changes, that change is not propagated to the hyperlink.

Therefore, I use a different technique for cross-referencing requirements from an external Word file. Word supports a field type called INCLUDETEXT. With this field, I can include a piece of text from a bookmark of a different Word file. The syntax is  {INCLUDETEXT "[file name]" [bookmark]}. Unfortunately, the file name needs to be an absolute path, which hinders working together in a team with this file. The solution is the following:

{INCLUDETEXT "{FILENAME \p}/../[relative path]" [bookmark]}

Using the approach from above for creating requirements, I can easily use the generated bookmarks to reference requirement ids or requirement titles, even across documents. Let’s look at the example again. I saved the document from the above example as “requirements.docx” and created a new document “references.docx”. From this second document I want to reference the requirement “My first requirement”, first the whole title then just the ID. Look below at the screenshot how this works out.

Conclusion

Microsoft Word surely is still not the best tool for documenting requirements. But using a few tweaks we can at least obtain a reliable numbering scheme for requirements and a reasonable robust requirements traceability.