Section 5. Naming Conventions and Definitions

5. Naming Conventions and Definitions

It has been our experience that all projects have their own unique vocabulary. Failure to use this project-specific nomenclature correctly inevitably leads to misunderstandings, hours of lost time, miscommunication between team members, and ultimately poor-quality specifications.

5a. Definitions of All Terms, Including Acronyms, Used in the Project

In section 5a of the requirements specification, start a glossary to define the important terms to be used by the stakeholders. This glossary should be enlarged and refined as the analysis proceeds, but for the moment, it should introduce the terms that the project uses and the meanings of those terms to your project.

Weather Station: A weather station is capable of monitoring air temperature, humidity, precipitation, and road temperature. Four road-surface sensors can be attached to one weather station. Each sensor must be within 1 km of the weather station.

Thermal Map: A region or other geographical area is surveyed to determine the temperature differences at various parts of the area. The resulting thermal map means the temperature at any part of the area can be determined by knowing the temperature at a reference point.

The names you use in the requirements specification should be the regular business namesthat is, the names that the business stakeholders use in their everyday work. However, be prepared to suggest better names if the existing ones are misleading or include references to obsolete technology.

Good names are easily distinguishable and self-documenting. They should invoke the right meaning, thereby saving hours of explanation. Create your dictionary by writing each term and its definition. Include all abbreviations and acronyms that are used by your users.

We suggest you add all acronyms and abbreviations. We often encounter situations where team members use acronyms, but admit they do not know the meanings of those acronyms. This section gives you a place to register your acronyms.

This section is intended to serve as a reference for all the people who work on the project. It is also used in the Quality Gateway to ensure that all terms used to write the requirements conform to the terms defined here.

5b. Data Dictionary for Any Included Models

The glossary described earlier is the basis for the analysis data dictionary. As the analysis data dictionary evolves, many of the definitions from the glossary are expanded in the dictionary by adding their data composition. We find it particularly useful to start the data dictionary here, as any models you include in your specificationwe cannot overstate the value of having a context model as part of itlack rigor without the attached data dictionary.

Use whatever dictionary notation you normally use. The notation is unimportant; the existence of the dictionary and the way you use it are important.