How to Produce Adequate Definitions
We know how important definitions are, yet we also know that definitions are often missing or of poor quality in data deliverables. Over the years, I have used a number of techniques to ensure adequate definitions exist. For example, one technique is to write the attribute definition before naming the attribute. This not only guarantees you'll have a definition, but you will also often come up with a better attribute name. What techniques do you use to produce adequate entity and attribute definitions?
Four main techniques for producing adequate entity and attribute definitions are:
Use a definition template. Definitions are easier to write and often more complete when the writer follows an established structure or builds upon classword or domain definitions.
DBA Adviser Jane Caddel begins with a generalization of the term, followed by a preposition such as of, by or which, and ends with a qualification that further explains its relationship to other objects, including what distinguishes the term being defined from similar terms. For example, the definition for the term "registration" could begin with, "An application by a student to attend a seminar."
Data Modeling Consultant Norman Daoust and Data Modeler Rich Kier both emphasize that the definition template requires a place for examples. Rich says, "You should always ask for three examples of something when you try and define it. Often, people will agree on the definition but then argue passionately about whether or not an example actually is one of the things they've just defined."
Lee LeClair, senior system engineer, builds a template for each classword - the classword being the last term in a data element name such as Code, Date and ID. "For each classword in our approved classword list, I have a template to get the definition started." Design Challenger Peter Heller follows a similar technique using domains instead of classwords. "Define a domain that encapsulates the meaning of the application attributes that will be derived from it."
Write definitions early and require an approval process. Senior Database Designer Carol Lehn says, "I always enter the definition at the time I add an attribute/column. If I can't write the definition, how do I know I'm adding the right piece of information or that it's named correctly? This also means I don't have to go back later and enter all of the definitions at the end of the project." Paul Horti, business analyst, follows a similar approach: "I always try and use the business term for the attribute, put together a strawman for the definition and then go back to the business to validate it." Larry Weismantel, business analyst, highly recommends an approval process: "New attributes are not allowed to be put into the production environment until a group has approved the definitions for them."
Cover your bases. By asking very simple questions, you can make sure you have the complete definition. Data Analyst Betty Carpenito and Data Modeler Terry Gaspari recommend (for each definition) asking what, when, where, why, how and who. Terry summarizes her approach: "Ask the requestor/businessperson these questions as they pertain to the entity or attribute: What is it by itself and, if relevant, in relation to other entities or attributes? What does it look like (examples of possible or valid values)? When is it present or absent (i.e., are there special circumstances in which you'd see it or not see it)? Where is its source? Where is its final destination? Why is it needed? How will it be used (i.e., online entry, reporting, translation, etc.)? Who (person, role, application, company, etc.) sets the entity or attribute, reads the entity or attribute, or uses the entity or attribute?"
Leverage existing definitions. Instead of reinventing the wheel, find other places where the term has already been defined. Sai Koduri, senior technical architect, recommends having a master list of definitions for industry-standard terms that can be reused across data models. Examples include product UPC or product SKU definitions in retail and the consumer goods industry. Senior Data Architect Ronald Warden says, "Initial development of definitions involves checking all known paper sources in the organization for pre-existing definitions. Then I reconcile those definitions, if possible." Johnny Gay, data analyst, says, "I put my computer to work searching for definitions internally on the company LAN and externally on Google. Most things already have good definitions somewhere."
Senior Data Architect Jeff Lawyer agrees: "The World Wide Web is a good resource for stimulating good definitions. (Don't forget to include proper attribution of sources to avoid plagiarism.) The most vivid example of this that I experienced was latitude and longitude. Everyone knows what they are and how they can be used when put together to form a geographical point, but try to put together a good, geographically accurate definition."
I have reviewed data models across many different industries, and I consistently provide feedback that the definitions have room for improvement. Applying some of the techniques in this challenge, however, such as using templates and answering basic questions like "Why is it needed?" can produce clear and complete definitions that receive high scores on model reviews.