I’m having a little trouble reading the spec – I left my secret decoder ring at home!
Ever hear that before? A set of requirements that makes perfect sense to one team member can be completely unintelligible to others. Requirements written in business-speak, or full of accounting jargon may be unintelligible to the development team. Unless you’ve staffed the dev team with switch-hitters, you have to provide supporting documents that explain this domain-specific information.
“Present the top 10 (lowest) P/E stocks to the user†– this message needs to be decoded – “P/E†is not unambiguous to someone who doesn’t know what it means.
Data dictionary = decoder ring.
Add a glossary to the requirements with a definition of ‘P/E’. If you use a system that supports it, link that definition to all of the references in the body of the requirements. Whenever someone asks “what does X mean†– you have a candidate for a new entry. This is just a sorted list of terms and definitions.
I developed requirements on a project last year for an internal accounting and management application for a major global manufacturer. This customer had extremely complicated pricing, discounting, rebating and accounting processes and systems. We were gathering requirements from SMEs all over the organization – sales, competitive intelligence, accounting, etc. We put together a specification, and validated the contents with those SMEs and stakeholders. We had a dev team of about 20 people, none of whom had ever written financial software, and none of whom had studied economics or business. On first glance at this validated spec, one of the many questions was “what is the definition of margin?†That’s when I stopped the presses and started a data dictionary. I don’t know that I can describe the palpable improvement in the quality of communication as soon as I did that. Palpablistic? Palpablistical? Nope. Can’t describe it.
We did this one as items within a Caliber RM repository, ultimately ending up with about 100 definitions. The guideline we use is to only add definitions for domain-specific information such as accounting or engineering terms, and not something a qualified team member could reasonably be expected to know (such as quarterly, acceleration, hierarchy). Next time, I may use a wiki, to provide both contextual and alphabetical sorting. The hyperlinking between definitions would also be helpful.
