I often get strange looks when I tell companies that I consult with that as part of their development standards, they should define a vocabulary list for both the department and per project. “Are we going to have a spelling test?” they ask. All joking aside, I explain to them that the more people involved in a project the more chance there is for misunderstanding, especially when it comes to the definition of a term.

A vocabulary list is an important communication tool that is a single, unambiguous source of definitions for common and uncommon words, terms and phrases used when discussing a project (or specific to the company’s domain). This prevents arguments and confusion between team members, developers and management and management and clients.

I once spent 30 minutes arguing with a developer about the exact same point. He said we should be doing X and I said we should be doing Y. Finally I asked him to define X and yeah, we wasted 30 minutes. A simple vocabulary list would have prevented that.

A recent example I ran into was with an offshore team. I’m working with them to implement promotions on a mobile app for my client. A request from marketing was to make sure the mobile promotions always pulled the latest product retail price from the pricing database. Simple enough, yes?

When I told the offshore team lead that we should can not use the retail price from the promotion definition (which was a static XML file) because it could be out-dated, the fun started. He was trying to determine where to get the retail price. “Ok, I will display the product cost from the Cost column”. Cost? Why the cost? The cost is what we, the vendor, pay for the item when we purchase it for our inventory.  To him it looked as if that was the cost for the customer.

Next he said “Ok, then I can use the sale price”. “No, not the sale price” I said. “That’s the discounted price for the promotion”. Sale in this case meant, “This product is on sale at a discounted price”. He thought it meant it was what the product was selling for since the product was “for sale”   and not “on sale”.

Finally I said to just use the retail price. “Retail” was a word not familiar with him (I assume it’s a translation thing?). Retail, I explained, is the original price that the product would be listed for on the website. The price that customers would normally have to pay to purchase the item.

Do you see the potential for confusion which in this case could have cost my client money? Simple terms such as Sale and Cost can easily be misinterpreted because they are ambiguous, or not understood at all as in the case of ‘Retail’. A developer following a spec may very well think he is on the right path when in fact he is way off.

What do you think? Discuss this on Hacker News