The (right) meaning of words

Yesterday night I was so tired that I didn't want to cook anything for dinner, so I decided to order some food to take away... but I noticed something very curious while reading the menu of my favourite "food to take away" shop. The picture in this post translates as:

VEGETABLES
Vegetable Chicken: lettuce, tomato, chicken, mayonnaise and boiled ham
Vegetable Tunna: lettuce, tomato, tunna, onion, boiled egg and mayonnaise
Vegetable York: lettuce, tomato, boiled ham and mayonnaise

First impression was: "OMG! didn't know that tunna and chicken were vegetarian food!". Then I realized that probably the guy who wrote the menu meant "sandwiches with vegetables (not exluding other ingredients)" and not "vegetarian sandwiches" when he wrote it. However, I understood vegetarian sandwiches at first glance.

If we were talking about software development, this missunderstanding may easily lead to a wrong development and hence to a work redo, deployment delays and general insatisfaction, both for the customer and for the tech team.

The worst thing that can happen in any software project is to develop the wrong project. And the main cause for that to happen is that requirements in plain language don't mean the same for all the actors involved in the project.

That's why one of the first artifacts you should create in any software project is a glossary of terms that clearly states the meaning of any important word for both the business and the project. Doesn't matter if you use user stories, use cases, plain text software requirements, all of them or any other kind of Software Requirements Specifications. The words that are important for the business, the project or the context must be clearly defined for all people involved. Of course, as any other project artifact, keep this glossary versioned.

But, how should this document be? Well, I think that there are no fixed rules for it as long as it works for you, but I will recommend you 3 simple rules that should keep in mind all the time:

• keep the document visible to all team members; put it in the first page of the wiki of the project if you use it, send it to all members every time it's updated... everybody should have no doubts about terms and its definitions.


• take it with you in all requirements gathering and development team meetings; force the use of the correct terms every time ambiguity appears and be sure ti have your ears ready to catch any word that may lead to confussion. If you're in doubt about adding a new term, then add it (I usually record meetings for later review).


• if a definition takes more than two or three lines, check if you can divide it; e.g., if you are writing a definition like "User: anyone who can search in the web, log in in user area, register preferences or anyone who use the backoffice of the web site...", probably will be better served by defining two terms, "public area users" and "back office users".

Also, if you use user stories for requirement gathering, user stories and glossary of terms can provide feedback to each other and serve to you as a way to improve the quality of your user stories and of your requirements.
And remember, a vegetable dish doesn't need to be a vegetarian one ;-).