It’s important that any software requirements document defines each of the major terms that are used in the document. When a term is defined, the document should be consistent in using that term throughout the rest of the document. For example, if you define the term “user” or “customer” or “member” in one place then use that word consistently though the document.
One common cause of complaint is sentences like this:
When a user logs into the system their member password shall be checked against the accounts table and if the customer login and password matches correctly then the person is logged in and their login record is updated to include the date of their last log in.
The above sentence uses the words user, member, account, customer, person, and login to mean the same thing. One term and one term only should be used to describe a person who logs into the system.
It is common practice to use the following terms consistently in all scope documents across all projects:
- User — try to avoid this term except in the most broad sense, it has negative connotations outside of the IT industry.
- Member — a typical user who has subscribed to some part of the system.
- Customer — a typical user who logs into the system for the purchase of goods and services.
- Administrator — a user who administers or assists in the administration of the system, who usually has a high level of privilege in the system.
- Contact — a customer, member, supplier, or other person who may or may not interact with the system at all (e.g. a person in a contacts database in a CRM system).
All of these definitions are placed into a section of the requirements document called a Project Glossary. Personally I believe it’s better to have the project glossary at the front of the requirements document, because then you don’t use words before you define them.
If words that are critical to the understanding and implementation of the project requirements are not defined in the project glossary then it is the job of the software architect to query back to the requirements writers to obtain definitions of all of these words. It’s often the job of the software architect to become the sole maintainer of the project glossary.
A project glossary should be formatted like a table. I prefer to keep mine in alphabetical order. So taking the above definitions, my glossary might be formatted like this:
The project glossary is an important part of the software requirements document and is used to aid in modelling the software.