As my department’s de facto technical writer, I spend most of my time working on document-related projects. One of the things I’ve been working on is a glossary of terms. Among other things, I’ve been trying to come up with a “dictionary”-type definition of the term “management entity.”
Unfortunately, I have not been able to find an adequate definition anywhere. I did a Google search, and the results were, to put it mildly, disappointing. I also tried the glossary in our application. Here’s how it reads:
A Management Entity (ME) is used by Capital (sic*) entities for Tax (sic*) and Financial Statement (sic*) purposes. Capital entities are matrix organizations with multiple businesses reporting in a legal entity, the ME represents that business’ activity in that legal entity.
(*Misuse of capitalization — ugh!!!)
This “definition” (and I use that word loosely) is nothing short of atrocious. I refer back to an article I wrote a while back about bad and useless definitions. This is one such useless definition. This blurb explains what (a “capital entity”) uses a management entity. It explains what it represents in relation to a capital entity. It explains the attributes of a management entity. It even explains what a “capital entity” is. But it never explains what a management entity actually is!!!
Explaining the attributes of a word is not the same as defining a word! I can tell you that a car has four wheels. That is not the same as explaining what a car is!!!
If you haven’t figured it out by now, this is a major writing pet peeve of mine.
I’ve mentioned before that you need to know your audience when you write. Since I’m working on a glossary, I assume that my audience doesn’t know much about the terminology about which I’m writing. When I tried looking up the definition for “management entity,” I kept finding references that either didn’t completely define the term or obfuscated it in legalese. The writers assume you know all about the topic. If I’m looking up a definition, then I likely don’t know about it. If I’m a beginner in a topic, I have a demand: explain it to me like I’m a five-year-old.
Unfortunately, this tends to be a failure when it comes to people trying to explain technical terms. To be fair, this is a skill that not everyone has (I previously wrote about how difficult it is to simplify concepts, and I even have an entire SQL Saturday presentation in which I talk about talking to non-techies). It takes time to develop that skill. The problem I have is when an SME (subject matter expert) tries to explain a concept, and when the audience doesn’t get it, the SME’s attitude is one of, “what are you, stupid?”
Well, yes, as a matter of fact, we are stupid. We have no idea what you’re talking about.
Last night, Andy Mallon spoke at our user group meeting. He spoke about data compression. As part of his presentation, he provided an example using a common index out of a cookbook. He showed how the index would be changed if data compression was applied to it. The example provided a clear picture of the concept, and it allowed me to better grasp what he was presenting. That, to me, is a great example of making it simple!
If you’re trying to explain a concept, the worst thing you can do is dance around a definition or obfuscate it in terminology that only you and your cohorts can understand. Explain it to me like I know nothing about it — because more often than not, I don’t.