As software developers, we have a job to push back on unclear requirements and to help achieve a clearer, and importantly a shared understanding of the system.
Most users will not be versed in creating contracts. As a result, ambiguous terms will creep in without the user realising. Phrases such as 'The interface must be intuitive' don't make our jobs any easier.
When I receive these types of requirements I used to spend time reading and marking the documents by hand. This can be quite a laborious process and is very dependent on the experience of the reviewer.
I've been using a technique to help me become more consistent at giving feedback on requirements and to help establish a shared vocabulary of ambiguous terms.
The idea is simple. Create a document with all of the terms you know of which lead to ambiguity, then create an index showing where each of these terms appear in the requirements document.
I'm afraid I'm a Microsoft Word man, so the technique will need to be adapted to your personal tool of choice.
Grab a copy of the text in this list of ambiguous terms. Pop it into a new word document and save the document somewhere.
Take a copy of the document to be reviewed (the target document). You will be altering this document and don't want to change the original.
Make ALL of the text lower case within the target document (explained in a moment)
Use the 'automark' feature to highlight the terms in your 'requirements' document. This feature asks you to select a source document for the automark entries. (In Office 2007 this is found under the references tab, 'insert index', then select the 'Automark' option.)
At this point, Word has marked each phrase in the target document where the phrase in the 'ambiguous terms' appears.
Now, to create an index showing the user where the terms are:
Insert an index using the index feature within Word. In Office 2007, this is in the 'references' tab under the index section.
Finally, review the usage of the terms in context and send appropriate comments back to the user.
The automark feature of Microsoft Word is not the greatest for this usage, but if you are prepared to follow these steps and develop your own version of the ambiguous terms document (and share it with others in your team), this will help contribute toward better quality requirements.
In particular, I dislike the requirement for the ambiguous terms document to need two columns, both containing the same text. I haven't looked to solve this, let me know if you do!
In itself, the process is not fantastic. But if you share a master copy of the ambiguous terms document, then the whole team can contribute their experienced view to improved requirements.
(The concept here was unabashedly taken from Code Complete by Steve McConnell. Grab a copy and read it, highly recommended).
Update: I've pushed the 'Acceptable Terms' doc into a published Google Doc here
http://docs.google.com/Doc?id=dgdfgwms_5cp9v8k
and have updated the URL's above
