Explain it to me like I’m a five-year-old

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.

Advertisements

SQL Saturday #855 Albany announced!

The Capital Area SQL Server User Group (CASSUG) is pleased to announce that, for the sixth time, we will host SQL Saturday #855, Albany on July 20!

For additional information, to register for the event, or to submit a presentation, click the link above!

I’ve already submitted presentations, but I will be there, regardless of whether or not I’m picked to speak!

Hope to see you there!

“So what, exactly, are you doing in IT?”

“Aside from mediocre marks in his freshman literature courses — even MIT wanted people to be literate, but evidently Peter Zimmer didn’t care for poetry — the kid was straight A.” (bold type added for emphasis)

— Excerpt from The Sum of All Fears by Tom Clancy

As I mentioned before, a lot of things came out of SQL Saturday #814 — enough that I have enough ‘blog article material for at least a few days.  This is the first of those articles.

At the Friday night speaker’s dinner, Eugene Meidinger asked me what I thought was a very good and valid question.  I’m paraphrasing what he said, but he asked me something like this.

“I’ve been reading some of your ‘blog articles.”  (Ed. note: hey, someone reads my ‘blog!)  “Most of your articles don’t have anything to do with SQL.  Do you ever write anything about SQL?  How did you get involved with SQL Saturday?  Are you one of those people who just happened to latch on to SQL or hang out with SQL people?”

The answer is not simple.  This article is my attempt to answer his questions.

To answer his first question, yes, I have written about SQL, but it’s been a while.  For his (or anyone else’s) reference, here are some of the SQL articles that I wrote.

Yes, I do have experience in SQL Server.  However, I am not a SQL MVP, nor do I consider myself a SQL expert.  As I describe myself, “I fall under the category of knowing enough SQL to be dangerous.”  (Or, as I like to think of it, I know enough SQL to be able to do the job.)  Although I don’t know enough to be able to talk about advanced SQL techniques, I can discuss beginner-level SQL topics that can help people just getting started in SQL.  I’ve been meaning to write and present more beginner SQL-related topics, but (primarily) lack of time has kept me from getting them done.

(I’m also at a bit of a disadvantage because I currently work in an Oracle, not a SQL Server, environment.)

I won’t rehash how I got involved with SQL Saturday (I’ve already done that; I’ll leave it to you to check the link and read it for yourself).  I’ll just simply say that, although I don’t talk extensively about SQL topics, I’ve learned that there is still a place for me within an endeavor such as SQL Saturday.

When I first started my ‘blog, I intended for it to supplement my SQL Saturday presentations.  Since then, however, it seems to have taken on a life of its own.  It’s become a forum for me to express my thoughts in a way that they’d be helpful for both myself and for other people, especially anyone pursuing professional careers.

One thing that has come out of these efforts is that, professionally, I’m finding myself more and more.  I’ve had to come to terms with my own level of technological knowledge and expertise.  For years, I’ve been seeking positions in programming and application development.  But a funny thing happened along the way.  I discovered that while I do enjoy coding, I wasn’t passionate about it.  I wasn’t willing to spend late nights and downtime doing more with it or to immerse myself in it.  As soon as I came to that realization, that was when I realized that I should look into something else.

And as soon as I came to that realization, good things started happening for me.  I became happier and more confident in my career direction.  I started getting more and better opportunities.

It also made me realize that, despite all my jokes about being an odd man out because I was “not a SQL expert,” there is still a place for me in SQL Saturday.  No, I may not be presenting SQL or data topics, but I am still making important presentation contributions to the database and IT communities.

Back when I worked at Blue Cross in the late 90s and early 2000s, I fulfilled a role in which I supplied server staff with information they needed to do their jobs.  As I describe it, my job was to “support the support staff.”  It’s only within the last few years that I really appreciate just how important of a role that was.

Ironically, although Eugene asked me the original question, it was one of his own presentations that made me come to this realization.  The increasing difficulty of keeping pace with technological trends contributed to my waning passion about some technological topics.  I mentioned a while back in a podcast that I thought it was important to play to your strengths.  By focusing on something about which you’re really passionate — in my case, it’s technical communication — there’s no telling how far you can go.

So Eugene, if you happen to be reading this, hopefully this answers your questions and gives you a perspective of where I’m coming from.  (Good to see you this past weekend, by the way!)  And for anyone else reading this, hopefully this will inspire you to reflect upon your own interests and skill sets, and provide you with a sense of guidance as you pursue your career interests.

SQL Saturday #814, Washington, DC — this Saturday

This is a reminder that this coming Saturday, December 8, I will be speaking at SQL Saturday #814!  I will be giving the following two presentations.

  • Whacha just say? Talking technology to non-technical people — This is my original presentation — as in the very first SQL Saturday presentation that I ever did!  I’ll talk about techniques for talking about technology to people who don’t understand it.
  • Networking 101: Building professional relationships — from my oldest presentation to my newest!  This presentation is becoming one of my best sellers!  In this discussion, I’ll talk about the art of business and professional networking.  We’ll even do some networking during our session!  If you have business cards to trade, bring them with you!

SQL Saturday is always a good time!  I’m looking forward to making the trip down to the Beltway this weekend.  Hope to see you there!

Upcoming speaking engagements

I have a couple of confirmed speaking engagements coming up in the next few months!

I’m sure I will be adding to this list as more speaking opportunities come up.  Hope to see you there!

How do different cultures use your documentation?

The other day, I sat in a meeting in which we were talking about our product documentation, and someone mentioned something that had never occurred to me.

It had to do with who used our product documentation.

I found out that native English speakers (for the sake of this article, I’ll refer to them as “arch-typical American end-users” — whatever that means) mostly ignored the documentation (that I had written), inferred what they needed primarily from the application interface, and used the documentation primarily as a reference source.  This was something I’d anticipated, so naturally, I developed the document with that mindset.

However, I learned that users whose first language was not English utilized the document much, much differently.  (Disclosure: I currently work in an office where the majority of my coworkers are Asian-Indian.)  Many of them first read the documentation thoroughly before using the application.

I don’t know how much these people used the document as a reference guide as compared to how much they used the UI — we didn’t go into that discussion — but it completely changed my mindset as to how to approach documentation development.  I haven’t (yet) done any research, but I am now curious as to how people from different cultures and backgrounds approach documentation.  I have no doubt that this topic has been researched; if anyone knows of any authors or references, feel free to say so in the comments section.

For those of you who don’t know me, I should mention that I am Asian-American (specifically, Korean-American), but I am a native English speaker.  I don’t speak any other language fluently.  I do not speak Korean (what little I know came from what little my grandmother tried to teach me and from M*A*S*H reruns), and my personal foreign language experience comes from my German classes in high school and college.  That puts me in a unique situation; when it comes to my writing, my initial audience is American-English speakers, but my ancestral background makes me appreciate audiences from other cultures as well.

Cultural differences in communication are always an interesting topic.  I remember reading an article about how Chevrolet had issues with selling a particular model of their car in Spanish-speaking countries, because “Nova” translates to “not going.”  I also recall a conversation with someone who mentioned that a simple American gestures as a thumbs-up is the equivalent of “flipping someone the bird” in some other countries.  So it goes to show that what you’re trying to communicate could actually be miscommunicated, depending on your audience’s culture.

I’ve espoused time and again that a writer needs to know his or her audience when developing a document, and I continue to do so.  This realization made me realize that my audience is more diverse than I thought it was, and that I will need to plan for that whenever I am developing documentation.  And it’s not just a matter of what I’m writing in my words — it’s also a matter of how my document will be used.

So I guess the moral of the story is to be wary of what you’re writing.  You never know who will be reading — or how they will be using it.

Write it down, stupid!

Years ago, I went to visit my brother at his place in Queens.  I remember sneaking a peek into his home office.  As a reminder to himself, he’d stuck a label on his computer monitor with four words, in all caps: WRITE IT DOWN, STUPID!!!

This is pretty much my own mantra as well.  Any time I have an important task that needs to be addressed, I’ll do one of two things: either 1) do it right away, or 2) make a note to take care of it later.  I know myself well-enough that if I don’t do either, the task will either not get done or an important deadline or opportunity will be missed.

There is a reason why technical communication is such a passion of mine.  I’ve seen countless examples in the professional world where things are not documented.  I’ve heard a variety of excuses of why they’re not documented: “Oh it’s not that difficult to remember.”  “It’s intuitively obvious.”  “It cannot be missed.”  “I won’t forget that one.”  “I don’t have to bother with it now.  I’ll get to it later.”  And so on.  And so on.  And so on.

It’s not just professional communication, either.  When was the last time that you came up with a great idea that could change the world?  Did you write it down?  If you didn’t, do you even remember what it was?

I’ve long been a believer that open and honest communication is a game-changer.  Indeed, I’ve often told people that “90% of the world’s problems can be solved through communication.”  (Before you ask, no, I don’t have any hard evidence or statistics to back that up, but it is something I believe.)

Writing things down is a core part of communication.  When you write things down, you aren’t just communicating with other people; you’re communicating with yourself — your future self — as well.