Chapter 3 Using Styles and Properties
This section describes the advantages of using documentation styles and properties over ad hoc document formatting.
Microsoft Office was not intended as a software development tool yet analysts spend more time working with text in a word processing application than possibly any other tool. Why! Because it is the lowest common denominator application that everyone who needs access to the requirements, is familiar with. This means that analysts often find that their development tools are specified by the business. Can you imagine your programmers being told that the only tool they are going to be given to write code with is Notepad?
I like to think of requirements as a form of software, but at a higher level of abstraction than source code or design. Ideally they are expressed in a formal language, but previous attempts to specify requirements in anything other than a natural language have mostly failed. Why is this?
Formal languages are difficult to understand and even more difficult to write (look at requirements specified in Z, VDM and OCL for example). Personally, I find it easier to read and write code than to write formal language specifications. Reviewers of requirements want to read them in a natural language that they can understand. Using a formal language will generally mean that the requirement have to be specified twice.
So let’s forget formal languages and ‘real’ requirements management tools and assume that our requirements are going to be written using natural language with a word processor.
We can at least go some way towards formalizing requirements written in English. As mentioned earlier, we already removed many English words from our requirements specifications; adjectives and adverbs for example. Other improvements are to introduce a glossary into the project. We want to restrict the use of English to a minimum subset of the language. If two words can convey the same meaning choose one, and use it consistently (we are not writing a romance novel; requirements are boring on purpose).
Other ways to make our requirements documents consistent is to make use of MS Word properties and styles. This chapter describes some best practices for using properties and styles with MS word.
- baldrick's blog
- Login or register to post comments
- 897 reads
3.1 Properties
One tool that MS Word provides us with to help with consistency is the ‘properties’ feature. Terms that are to be used consistently throughout a development effort may be assigned to a property. Instead of typing the word into your requirements document, select the property, insert it at the appropriate place and it will look the same wherever it is used. If at some stage the project decides to rename the word, it is simply changed in the property field and all instances of its use are automatically updated.
These are some candidate properties for your MS word document:
· Document type – specify this in the document template as a property, and it never needs to be typed into the document.
· Document name – the document name is used is several places in the document. If it changes it only needs to be changed in 1 place.
· Saved date – use a field property that is automatically updated whenever the document is saved. The ‘Save Date’ field is built-in to Word.
· Version # - this number changes quite frequently, and as such is a good candidate for a property.
· Frequently used terms – any term that is used frequently throughout the document, such as project name, product name, project or document number.
Figure 1: Document Properties Window
Properties are defined through the ‘Custom Properties’ window.
Properties that are defined for this document include the Document Name (Document Name) and Version # (Version 0.1).
To change a property value as it is viewed in the document, you must select the property and execute an ‘Update Field’ command.[1]
Figure 2: Updating the Document Version
Once you have created your set of document properties you will want to use them in the body of the document. Whenever it is appropriate to use a property value simply insert the property field code instead of typing its value.
For example, many documents introduce themselves with the text ‘The purpose of this <document name> is to etc’. Instead of typing the document name, insert the ‘Document Name’ property as a field code. The following shows the code that actually gets inserted; ‘The purpose of this Document Name document is etc’. By toggling the field code the actual document name is displayed.
Figure 3: Toggle Field Codes To Change Between the Property Name and its Value
For details on how to use properties with MS Word 2007 see my presentation on Working With Styles And Properties.