I while ago I attended a presentation by the CEO of a company that specializes in translating documentation and helping other companies improve their customer-facing documentation. Their goal is to make it easier for the average Joe to understand complex documents.

The processes, she explained, went like this: a bank produced forms and legal documents filled with jargon, and hard to understand. Her team kicked in and helped them improve them. At the end, even your grandma would be able to read and understand it.

From all the scary forms and legal documents I’ve seen out there, I would say that her company will never run out of business.

During her presentation, she explained parts of the process her team sets when bootstrapping a project, and explained that in these kinds of projects, it was critical to develop a glossary and writing style guide from early on.

What struck me the most was that by the end of her talk, everyone in the room seemed to agree that they should create a glossary for the products/services for their own companies.

Validate if you really need a glossary

So, it’s Monday. You are all excited because over the weekend someone told you that you should make a glossary and style guide for your product/service. Before you start thinking about creating all that, ask yourself if you really need it. Do you:

1. Sell critical systems or services?
2. More than three team members create the customer-facing documentation for your product?
3. Work in a specialized field and really have to use jargon, or words that have multiple interpretations?

In the first case, it's easy to understand why one is necessary. If for you length means meters and for another team member it means miles, the rocket you're building might just crash.

On the other hand, even if you don't work with critical systems, if more than three people create and edit customer facing documentation, your docs might start to look and feel inconsistent. Trust me, when this day comes, you’ll know it, so don't stess about it.

Finally, if your area requires using technical jargon or ambiguous words, you might consider creating a style guide. As an example, if when you write 'deploy your ASP application to the Production environment', and it might not be clear for everyone what deploy, ASP, application, Production, and environment means. However, if you are writing for a technical audience, you might assume that some of the jargon is well known.

Why avoid style guides

So, what harm can come from creating your own style guide?

1. You will spend so much time creating a glossary, that you could be spending on other stuff. Stuff with real impact on your business.
2. Since your product/service is constantly evolving, the glossary will soon be outdated. It will require a continuous effort to ensure it is up to date.
3. You have to constantly sell it. To ensure everyone is on the same page, you’ll need to create processes that ensure everyone uses it. If you have a glossary and no one uses it, then you have wasted your time.

One important thing to notice, is the “you have to constantly sell it” part. It seems a bit irrelevant but when the speaker’s company his hired by a bank and she decides to create a glossary, do you think anyone will maintain it after her company has finished the service?

When this need comes from within the company, I think people really strive to make it work. But when some external consultant or boss creates a glossary and tries to push everyone else to use it, do you think anyone has the incentive to keep it up to date? Someone might try to do it just until work starts accumulating. Then these things that require constant maintenance and are difficult to measure their return, end up going to waste.

Creating a glossary is one of those things that will end up consuming lots of time. Even if its creation cost is low, maintaining it and ensuring everyone knows about it will take time.

So before getting all excited, and firing up your Excel, think about it for a while and validate if you really need one. Deciding not to do something is just as important as deciding what to do. Because every minute you are doing something, is a minute that you are not doing something else that could add more value to your work.