Definitions that aren’t

This is yet another item that can be listed under tech writing frustrations.

I was working on a project where we needed to rewrite a set of glossary definitions.  I won’t go into the definitions (primarily due to corporate privacy), but for illustration purposes, let me use this analogy.

Let’s say you’re looking up a definition for, say, a car.  You come across the following glossary listing: “A car has four wheels.  It is made of metal.  It is not a boat.”

This tells you about some of a car’s attributes (four wheels, made of metal) and what it isn’t (a boat).  It never tells you, in any way, shape, or form, what a car actually is!

Yet this horrifically-written glossary is entirely made up of “definitions” (and I use the word loosely) written just like this.  I don’t know about you, but my assessment of these glossary definitions would be “totally useless.”

I come across “definitions” like this more often than I want to say, and they make me cringe.  People look up word meanings to find out what words mean.  Writing a “definition” that describes only its attributes is useless.  If a glossary “definition” does not “define” what it is, then it does not do its job.


Keeping it simple: it can get complicated

“Everything should be made as simple as possible, but not simpler.”
— Albert Einstein

“If you can’t explain it to a six year old, you don’t understand it yourself.”
— also supposedly by Albert Einstein

If you’re on Facebook, I’m sure that you’ve seen the memes that go something like this: “tell a sad/scary/happy (whatever) story using only four words.”  It’s hard to do, isn’t it?

Welcome to the world of technical communication.  One communication tenet that I constantly preach — and you’ll hear me talk about this time and again in my presentations — is the KISS principle: “Keep It Simple, Stupid.”  Ask anyone involved with technical writing, documentation, or professional communication, and I’ll bet that most, if not all, of them will mention the KISS principle in some way, shape, or form (maybe not in those exact words, but you get the idea).  The goal of communication, after all, is to transmit information from a sender to a receiver.  If the message being conveyed is easy enough for the receiver to understand, so much the better.

However, here’s the irony: making things simple is difficult!

How often have you been asked to write something for knowledge transfer, and ended up with something that was nearly incomprehensible?  (Don’t be afraid to admit it; hey, I’ve done that, too!)  Whenever we’re tasked with writing documentation, our tendency is to explain every little tidbit of knowledge that’s in our head.  When that happens, we end up writing a huge paragraph of black text that nobody — and I mean, NOBODY, including yourself — wants to read!  That is not conveying information; that is obfuscation.

So how do we go about making things simpler?  For starters, I discuss some ideas in my previous articles about designdocument frustration, using examples, and talking to non-technical people.  I won’t rehash them here; I’ll leave it to you to go back to read those articles.

Additionally, here are some more thoughts that might be helpful.

  • Include only information necessary for the task at hand.  Avoid the tendency to include every last detail.  As a former manager was once fond of telling me, “don’t tell me how to build the clock; just tell me what time it is!”  I also remember a time back when my father was first learning about PCs.  He kept asking me questions about how the CPU and memory worked.  I finally said in frustration, “you don’t have to know how an internal combustion engine works in order to drive a car!”
  • Put yourself in the reader’s shoes.  When I wrote one of my very first technical documents, I said to myself, “okay, let’s say I’m the night operator who needs to use this document.  What do I want to see that would help me?”  That mindset resulted in a very successful document.  Reader empathy goes a long way.
  • I’ve said it before, and it’s an old but true saying: a picture is worth a thousand words.  A good illustration can convey a concept that’s difficult to do in words.
  • Avoid using long (or multiple) words when a simple (or single) word will do.  I think this is self-explanatory.
  • Voice matters.  Below are two sentences, one using active voice and one using passive voice.  Question: which one is easier to read?  Advice: try sticking to active voice.
    • Active: “John mowed the lawn.”
    • Passive: “The lawn was mowed by John.”
  • Formatting is a big deal.  Check out documents that you found easy to follow.  Pay particular attention to paragraph length, whitespace, headings, and so on.

People — myself included — say that the easier you can make things, the better.  The fact is, we humans only have a limited attention span, and we neither have the time nor the patience to comprehend complex information.  Simplifying things helps — but it’s also hard to do.  If you ever believe you know a lot about a concept, try explaining it to a child — and see for yourself how easy it is.

Setting a good example

I was recently tasked with a project where I would be assisting with developing a data governance document.  Trouble is, I have no idea what a data governance document is supposed to look like.  I looked at what my colleagues had written so far; what they had written looked pretty good, but it still didn’t really give me a good idea as to what the end product would eventually look like.  So I ran a Google search for “data governance document examples.”  Among other things, I came across a PDF document by the Federal Highway Administration, which includes a section called “Data Governance Plan.”  Okay.  Now I have something to go by.

How often have you heard things like “set a good example,” “let’s look at this example,” or “here’s an example of…”?  Whenever I need to look something up, more often than not, the last thing I use is a dictionary definition, or syntax description.  Most times, the first thing I’ll look up is an example of what I want.

Let’s see an example of — well — an example.  More often than not (as I’m sure most of you do), I’ll need to go online to look up things I don’t know very well — like, say, function syntax.

Let’s take, for example, a simple SQL SELECT statement.  I looked up the SELECT statement on MS Books Online and came across this syntax definition.

-- Syntax for SQL Server and Azure SQL Database

<SELECT statement> ::= 
 [ WITH { [ XMLNAMESPACES ,] [ <common_table_expression> [,...n] ] } ] 
 [ ORDER BY { order_by_expression | column_position [ ASC | DESC ] } 
 [ ,...n ] ] 
 [ <FOR Clause>] 
 [ OPTION ( <query_hint> [ ,...n ] ) ] 
<query_expression> ::= 
 { <query_specification> | ( <query_expression> ) } 
 <query_specification> | ( <query_expression> ) [...n ] ] 
<query_specification> ::= 
 [TOP ( expression ) [PERCENT] [ WITH TIES ] ] 
 < select_list > 
 [ INTO new_table ] 
 [ FROM { <table_source> } [ ,...n ] ] 
 [ WHERE <search_condition> ] 
 [ <GROUP BY> ] 
 [ HAVING < search_condition > ]

Is this correct?  Sure.  But how well can you follow it?  For example, what is significant about items in square brackets (“[]”)?  What about items in angle brackets (“<>”)?  How about the pipe character (“|”)?  It takes some time to understand or follow what they’re trying to tell you.  Maybe it’s helpful when you’re trying to understand a concept, but when you’re trying to understand something quickly, this might not work very well for you.

On the other hand, when I scrolled down on the page, I came across a few examples.  Here’s one that illustrates the HAVING clause that I randomly grabbed from the page.

SELECT OrderDateKey, SUM(SalesAmount) AS TotalSales 
FROM FactInternetSales 
GROUP BY OrderDateKey 
HAVING OrderDateKey > 20010000 
ORDER BY OrderDateKey;

Looking at the example, how much better can you comprehend a SELECT statement syntax?  For me, personally, the example works much better than the statement syntax above; I understand the syntax much better by the example than I do by the syntax definition.

How about something for those of you who don’t understand SQL and have no idea what I wrote above?  What about something like, say, a word pronunciation?  I tried to think of a difficult word to pronounce.  I figured the last name of Duke basketball coach Mike Krzyzewski would be a good one.  Wikipedia lists the following for pronouncing his name: “/ʃɪˈʒɛfski/” and “shih-ZHEF-skee.”  Can you easily use /ʃɪˈʒɛfski/ to pronounce his name?  Probably not.  You need an understanding as to what the pronunciation symbols mean.  Granted, clicking it brings you to a pronunciation guide that explains it.  But even so, you still need to look up the symbols, and you need to figure out how to use the guide.  That takes time and effort.  On the other hand, most native English speakers can look at “shih-ZHEF-skee” and have a pretty good idea as to how to pronounce Krzyzewski.

I’ve written in previous articles (check out my articles on tech writing frustration, design, and talking to non-techies) that illustrations are worth a thousand words.  Examples are types of illustrations.  While examples may not necessarily be pictorial, they serve the same purpose: illustrating a concept in a way that’s easier to grasp than just a definition.

We’ve often been told that we should “set a good example for others to follow.”  That’s usually said in the context of how we behave.  However, it can also apply to how we communicate as well.

Technical writing: the Rodney Dangerfield of tech professions

“It exists!” he cried.

“No,” said O’Brien.

He stepped across the room. There was a memory hole in the opposite wall. O’Brien lifted the grating. Unseen, the frail slip of paper was whirling away on the current of warm air; it was vanishing in a flash of flame. O’Brien turned away from the wall.

“Ashes,” he said. “Not even identifiable ashes. Dust. It does not exist. It never existed.”

“But it did exist! It does exist! It exists in memory. I remember it. You remember it.”

“I do not remember it,” said O’Brien.

— Excerpt from 1984 by George Orwell


“If it isn’t documented, it didn’t happen.”  — Sohail Sangi

Chores.  Taking out the trash.  Doing the dishes.  Cleaning up the room.  You don’t like doing them.  Neither do I.  Yes, I’ll admit it: I’ll do just about anything to avoid doing them.

Chores exist in the workplace, too (filling out your timesheet, checking your email, and so on).

However, documentation is not a chore.  Why do I say it isn’t?

Because chores at least get done.

A show of hands: how many of you work in a place where everything is well-documented?  Obviously, I can’t see everyone’s hands, but I’d be willing to bet that not a lot of them go up.

I have seen way too many cases where documentation is ignored — often blatantly so.  In my tech writing presentation abstract, I go as far to say that “documentation is one of the most critical, yet most blatantly ignored and disrespected tasks when it comes to technology.”  I go as far as to compare documentation and technical writing as being the “Rodney Dangerfield of technology tasks.”  It gets absolutely no respect at all.

I once told someone that I had technical writing experience.  His response?  “I’m sorry.”

As someone who harps on documentation and communication, this baffles me.  It absolutely bothers me when important things are NOT documented.

Folks, I get it.  I understand that people don’t like to document.  It’s not a sexy task.  Some people believe that watching grass grow and paint dry is more exciting than writing documentation.  People don’t like doing it.

But the fact is, it’s important!!!  Here is a sampling of links I found that describe why documentation is critical.

Occasionally, when I have an idea for a new presentation topic, I’ll post it to the forums on SQLServerCentral for feedback.  When I posted my idea for my tech writing presentation, one of the most profound responses I received was from Jeff Moden, who wrote this response.

So why are documentation and technical writing tasks so universally hated and disrespected?  I don’t have any evidence or data to answer this question (maybe if I decide to pursue a Ph.D, I might focus on this as a point of research), but I can speculate on some possible reasons.

  • “It’s boring.  I just don’t want to do it.”  To my knowledge, nobody has ever said that documentation was fun (well, there might be a few people out there, but I digress).  But there are some ways to make it more fun (more on that below).
  • “I can just remember everything in my head.”  This probably qualifies as being one of the biggest lies of all time.  Can you tell me exactly (and I really mean exactly) what you had for breakfast yesterday, or the day before (or this morning, for that matter)?  Yeah, I didn’t think so.
  • “Nobody documents anymore.  It’s not a big deal.”  See my comment above.  This is another huge lie.  Especially in this day and age where misinformation spreads like wildfire, documentation is critically relevant.
  • “It’s not a priority.”  It absolutely must be a priority.  Documentation needs to be included in project planning.  Make sure that time is budgeted for documentation.  It is that important, people!
  • “I just don’t have the time.”  See my bullet point above.  Make the time, damn it!!!
  • “I’m not a very good writer.”  Not everybody is.  Keep reading for my thoughts on this.

So what are some possible solutions to these issues?  Again, I am speculating on a lot of this, but here are a few things that seem to have worked.

  • Always follow the KISS principle.  Keep it simple, stupid!  This may be one of the oldest rules in the book.  Nobody wants to write a lot of detail, and nobody wants to read it, either.  Sometimes, the less you write, the better.
  • Find a way to make tools easily accessible.  Some of my past jobs included keeping a “scratch notes notebook” (in pre-online days) or incorporating a departmental intranet, Wiki, or team collaboration product (such as Confluence, GitHub, or SharePoint).  Having the tools readily available makes it more likely that they will be used.
  • Establish guidelines.  It seems like people are more likely to document when rules are laid out for them.  It can be something as simple as creating a template for people.  I’ve noticed that when documentation guidelines are established — developing a template or a form for people to use, asking people to write comments when coding, and so on — people tend to stick to them.
  • Document your code.  I had professors in college who used to dock points from my project grades if they weren’t documented or commented, regardless of how good my code was.  If you’re a developer or a programmer, code comments are probably the easiest and most effective ways to document.  Code comments can explain, in just a few lines, what some pieces of code are doing and why some variables are being used.  This allows for easier code updates, troubleshooting, and debugging.
  • Don’t worry about grammar.  As a self-admitted grammar snob, this statement is probably anathema to people like me.  However, writing ability could be a potential roadblock to documentation.  Human beings tend to be self-aware about their mistakes, which prevents them from doing their best, and documentation is no exception.  If you are self-aware about how you write, go ahead and write without grammatical restrictions.  So long as ideas are conveyed and understood, it should not be a roadblock.  If your document needs to go to customers, have an editor (or someone who knows what they’re doing) review it and make it look pretty later.
  • Find a way to make it fun.  Even my own attention span is reduced and my eyes glaze over after spending a couple of hours working on documentation, especially text.  However, I’ve noticed that working on some types of documentation — especially anything that involves illustrations, visualization, and UX/UI — tends to keep my attention much more than writing instructions or text.  Humans are visual animals, and we are more receptive to visual cues.  Creating (and consuming) illustrations tends to be easier (and more fun) that consuming text
  • Be a subject matter expert (SME).  Maybe the answer is that you don’t have to write at all.  If you really don’t like to write, then make yourself available to someone who does, and let that person worry about the documentation heavy lifting.  Sharing your expertise contributes to documentation.

This is by no means a comprehensive list (as I stated earlier, I’m speculating on a lot of this).  If you have anything more to add, by all means, please do so in the comments.  Your ideas might just make their way into a future presentation or ‘blog article.

I absolutely believe that ignoring documentation is a recipe for disaster — maybe not immediately, but it will happen somewhere down the line.  These issues (and maybe some others I haven’t thought about) must be addressed.  Documentation can pull your butt out of the fire and save it.  The lack of it can guarantee that you go down in flames.

Looking Back

This is a reblog of a post from my friend, Steve Jones. He touches on a topic that is near and dear to my heart, and one that I strongly believe is crucially important.

Nearly all of my SQL Saturday presentations have revolved around documentation and technical communication. Technology may have changed over the years, but the importance of documentation has not. I strongly believe that documentation is getting to the point where it is being dangerously ignored, something that we, as technical professionals, cannot afford to do.

Voice of the DBA

Someone sent me this post on 40 years of programming. It’s a read that laments a few things and complains about many others. Most of the thoughts are opinions, and as such, you may or may not see validity in them. I suspect most of you, like me, see some things are mostly true and some as just false. Since I’ve been in this business for nearly 30 years, many of the comments bring back memories and thoughts about my career as well.

One of the things I do lament is the declining quality of documentation. I’ve seen the volume and detail decline over the years. I wouldn’t want to go back to paper, but I would like to see better examples and more complete examination of the ins and outs of the various functions and features. Far too often I find that there are examples, explanations, or behaviors…

View original post 398 more words

My hometown SQL Saturday: Albany, NY, July 29

My local SQL user group is hosting SQL Saturday on July 29, a week from this Saturday!

I will be speaking; I will be giving my presentation on documentation.  There are also a number of other presentations that people might find of interest.

When I attended SQL Saturday in New York City a couple of months ago, I sat in on Lisa Margerum’s session on networking.  It is an excellent session, and I recommend it highly.

A number of my friends are also presenting, including Greg Moore, Thomas Grohser, George Walters, John Miner, and Ed Pollack.  They always give good presentations, and I recommend them highly.  Check out the schedule for more details.

Hope to see you there!


SQL Saturday #638, Philadelphia

This coming Saturday, June 3, I will be speaking at SQL Saturday #638, Philadelphia (okay, it’s actually in a town called Whitpain Township, not Philadelphia, but that’s what they call the event, so…)!

I will be giving the following two presentations:

  • Tech Writing for Techies: A Primer — Documentation is one of the most critical, yet most blatantly ignored and disrespected tasks when it comes to technology. Businesses and technical professionals ignore documentation at their own risk. This session discusses what tech writing and documentation is about and why it’s critical for business. It also explores possible reasons for why it’s ignored, how documentation can be improved, and how “non-writers” can contribute to the process.
  • Disaster Documents: The role of documentation in disaster recovery — I was an employee of a company that had an office in the World Trade Center on Sept. 11, 2001. Prior to that infamous date, I had written several departmental documents that ended up being critical to our recovery. In this presentation, I provide a narrative of what happened in the weeks following 9/11, and how documentation played a role in getting the organization back on its feet.

    While other disaster recovery presentations talk about strategies, plans, and techniques, this presentation focuses on the documentation itself. We will discuss the documents we had and how they were used in our recovery. We will also discuss what documents we didn’t have, and how they could have made the process better.

Hope to see you there!