The Definition Writing How-To Road Map

ESTIMATED READING TIME: 10 MINUTES

Definition writing is hard.

There, we said it. And we know what we're talking about — we facilitate definition writing in big businesses for a living, we teach it for a living and we talk about it a LOT!

If you're doing definition work and you're not finding it hard, I'd be willing to guess you're not doing it well.

Tough call, I know. I could be wrong. But well-written definitions, ones that contain no ambiguity, ones that cover all the information IT need to understand the business requirements around those terms, ones that actually work as a single source of truth for the whole organisation…those are mighty hard to write…

…which is why they don't get written very often.

If you need to know more about why quick-and-dirty definitions aren't going to cut it, we've written other pieces on that topic here and here.

The Definition Writer's How-to Roadmap

If you're ready to up your definition writing game, here's our roadmap (road tested by experts) to help guide you through the difficult process of writing definitions.

1. Establish the scope of your definition work.

Assuming you're working on a project and that there's no formal glossary governance team to do this step, you need to understand what business terms are being used by the product owner or primary business stakeholder.

If you're present in the initial requirements meeting, make a list — perhaps a mind map — of all the business terminology that is being used. Otherwise, read through the requirements document.

Then do your research to find out which areas of the organisation also use those terms. This is a key step. Your organisation's intranet is the first port of call. Also check out any related legislative or industry websites.

2. Prioritise your business terms.

This means you take the compiled list, and you prioritise it based on either what's most pressing for your project, or most pressing for the organisation. What terms MUST be clearly defined for you to effectively write the requirements documents.

Based on your research, you should be aware of the terms that could be causing trouble.

Ideally, your organisation will build a central glossary that continues to define all its terms. But again, do the best you can with the scope you have.

With the list of stakeholders in your spreadsheet, ideally as a matrix with the terms, you should be ready for step 3.

3. Determine who should be present at the definition writing workshops.

Then invite them.

Start with the functional areas that absolutely must be represented in the definition writing process (i.e., the functional areas requesting or directly affected by the build). This could be quite a large group, that's ok, but we find between 6 and 15 is ideal.

If you're not constrained by a single project, or your project is building an initial glossary, then plan to roll out the awareness of what terms you're working with, even to all functional areas in the organisation. As I said above, I think having representation from all relevant areas is the only way to ensure total clarity and an effective glossary.

At the least, reach out to stakeholders in those other areas directly using the terms you've identified and prioritised for definition. Ask them if they'd be interested in helping to clarify the meaning of those terms.

This is always a bit of an internal marketing exercise, so make sure you can articulate the value this activity will provide for the organisation as a whole. In short, the "why" here is that there's a build underway that will either affect their work or their work may affect the build, and therefore it's in their best interest to be involved, to avoid worst case scenario mess ups which will negatively affect everyone.

Outline the approximate time commitment the workshops will entail (see below). Ask them to nominate individuals from their teams to be involved in the definition writing workshops. These should be individuals who have a comprehensive knowledge of the processes and data used in their functional area.

Remind invitees that new systems built without incorporating the language usage of their functional area can result in future IT builds or reports for their area being more likely to fail. Or even prove impossible. That can add up to higher costs, lowered capacity, increased work-around time etc. Better to be part of ensuring language consistency in the system builds!

Reiterate that you're only focused on the key, potentially troublesome, terms, not every term in the organisation — it's the 80/20 rule!

4. Book in all your workshops up front.

It's our approach to schedule up to ten initial workshops over a period of 5-10 weeks. You may not have this kind of time, so you may need to book more in each week. Of course, the number of workshops needed is driven by the number of definitions you're hoping to write.

But remember: if you're writing definitions for core terms (i.e., terms core to just about everyone's job - for instance, in an insurance company, these might be customer, policy, premium, coverage) you're likely to need several workshops per 1-3 terms. You'll revisit terms over several workshops, as participants go away, think about the issues with definition suggestions, and come back with new thoughts. That's just the way it goes with this work, and the more areas you have represented, the longer it may take (but the more robust your definition will be!)

Factor these kinds of timelines in when scheduling workshops.

5. Gather all existing definitions for the terms you're defining.

These may be in many different places, from different parts of the organisation. Learn as much as you can before the workshop about how the terms are used, understood, explained. Once again, your organisation's intranet is the first port of call (tip — do a search on the word "glossary"). And remember to check out any related legislative or industry websites.

Find the differences in these existing definitions — it's very likely you'll have workshop participants who don't really think this work is necessary and will say "we've got a definition for this in the X document, just use that". Be ready to respond to this by pointing out all the different definitions, from different documents, that can't all be true — they conflict.

You'll also need to be able to see through the current definitions, identifying where they are ambiguous, contain circular references, or simply don't explain the term sufficiently. This takes work and can be harder than it seems. Here's more tips on how to write a great definition. It will be particularly helpful if you can explain why the definition isn't satisfactory for IT builders.

Your job is to bring the knowledge and evidence needed into the workshops, to demonstrate why an existing definition isn't satisfactory.

6. Be ready to drive the workshop discussions.

This means starting strong, reveal the terms you're hoping to define in this set of workshops, explain briefly why it's so important and thank your participants for being there.

Then launch with your first term, showing the many definitions and talking through their contradictions or weaknesses. Keep asking participants for their ideas on what the term means — watch the discussions get fired up as people disagree with each other.

These core terms will be contentious.

When people get unruly, it's your job to rein them in. Remember, if a term is currently used to mean to different things, you may need to suggest one of these meanings be given a different term — perhaps just by adding an adjective or other qualifier — both things may be important to define, but each need a distinct term. This may not be popular, but when people see that no one has to "lose" their definition, they just need to change the official term their using to refer to it, then things may be easier to move forward.

It's also your job to ensure participants have covered all the necessary bases in their definitions. For instance, a university tyring to define "student" has to determine exactly when someone becomes a student, and exactly when they cease to be one. There may be many pathways to becoming and ceasing to be a student, and your definition needs to incorporate all possibilities (while not being longer than absolutely necessary).

You may find you need to spend time getting clear on things like life cycles and other associated processes. In the university example, we had to spend time defining the lifecycle stages of a student first, noting all the pathways and seeing where they converge in order to get clarity on what our definition of student needed to say.

It can be hard.

No, it will be hard. Sooner or later.

But this is what it will take to have real clarity and accuracy in your requirement documents.

7. Be ready to end discussions.

Some terms will perpetually be questioned and re-visited over time. However, you're working with limited time, so a workable definition will need to be finalised. If you feel the useful discussion has passed and the group is now arguing around minutiae, it's probably time to end the discussion and move on to the next term.

You'll take all you've heard in the discussions about each definition, write up your best attempt at a final version, and take it to your key stakeholders to approve or question further. They may decide it needs to go back to the wider definition writing group, they may not. Sometimes just seeing a finished draft is enough to quiet the dissenting voices and allow the definition writing to move on.

8. Make your glossary available to everyone.

We're big on using glossary software. In fact, we're big on it and fussy about it.

That's why we created our own (and we think it's the best on the market, so if you're looking for something, check it out here).

But key elements that make glossary software effective for business staff (not just IT) include being detached (though linkable in an appropriate way) from data management software.

Think that's crazy? Read this blog to understand why.

We also think your glossary software should incorporate the complex relationships between definitions, allowing cross linking in the definition to other term definitions, recognising parent/child/sibling relationships between definitions. In order to make your glossary useable, and to understand the impact of changing a definition, it needs to incorporate a useable taxonomy and ontology for describing the organisation's knowledge.

Your glossary software should also recognise the important link between terms and information artefacts, allowing links from each to the other.

Great glossary software incorporates accountability hierarchies and issue raising/management capability.

And finally, the best glossaries are owned and driven by business staff, not IT. This is because it's the business staff who use the language in practice, so they're the ones who know what they mean by each term. So, the software can't be too techy, too IT-focused.

Finally, we always stress that building a successful glossary is all about building a community. Your software needs to support that by being a dynamic and active, central hub for your language and information community to engage, define, manage and use your glossary.

Do your research well and make sure you choose glossary software that really works well on all these levels. If your company has already bought its software and it doesn't meet these criteria, we suggest contacting us for help using ours as a writing tool alone, as this can help with some of the downfalls of your current glossary software.

9. Ensure your definition work isn't just archived with this project's files on completion.

Use your definition work from this project for the next project (and each subsequent one), saving time and effort. This is where it pays to have incorporated as many functional areas into the definition writing process as possible and making your work artefacts accessible to all.

Doing this begins the building of an organisation-wide glossary, which is the ultimate goal of any definition work. Do it well, do it once for all the organisation, then you only have to ensure terms are managed and kept up to date over time.

Join the discussion on LinkedIn