Requirements Model Glossaries

All requirements model documentation is an art form when it comes to choice of vocabulary. It has to be readable by the stakeholders who commissioned the requirements in the first place, but also needs to be read with the same meaning by the development and testing community. The two areas of knowledge typically have huge gaps in their understanding of each others’ domain.

A common manifestation of this is the copious use of abbreviations within the business domain. Three and four letter abbreviations are spoken of in everyday business discussions, and in some cases even used as verbs! For example, on a recent contract at Transport for London I worked on a project called FTP. Most of the world understands this abbreviation to mean the internet File Transfer Protocol. At TfL it was the abbreviation used for the Fares and Ticketing Project.

A glossary is a list of business domain terms together with definitions written using words and examples that people not working regularly in that business domain could use to understand the scope and meaning of the business domain terms.

Ideally a glossary should automatically hyperlink to each of the terms whenever they get used in the documentation. Thus, as a requirements analyst writes a technical term into a part of a use case description for example, the term would spot that it is in the glossary, and automatically convert itself into a cross reference to that term in the glossary. The Use Case Editor does this.