The art of talking technology to non-technical people

“Eschew obfuscation.”
— unknown

Let’s discuss how to tie a tie.  First, you take the tie and put it around your neck, making sure that it lies within your shirt collar.  Make sure the seam is facing toward your body, and the wider end of the tie hangs down roughly two-thirds of the length of the tie.  In other words, the wider end should hang down farther than the narrower end.  Take the larger end over the narrower end.  Wrap it around once so that it forms a knot.  Take the larger end and put it through the knot you created.  Once that’s done, pull it tight.  Adjust your tie by pulling on the narrow end, which should now be behind the wide end.  Your tie should now appear neat and flush against your shirt.

Raise your hand if you actually followed the above paragraph.  And when I say “followed,” I mean that you read (as opposed to skimmed) through the entire paragraph, following every step and not falling asleep while reading it.  I’ll bet that not a lot of hands are up.

Yet this is exactly the way that so many technologists tend to write when they are asked to convey a set of instructions.  They will write (or talk) in lengthy detail, explaining every little thing and believing that the reader (or listener) is soaking up every detail and is in rapt fascination of the subject, holding on to every single word.

Oh, if only that was true.  If that was the case, we wouldn’t have technical writers.

I wrote a couple of articles a while back about tech writing frustration and why design matters.  They provide some thoughts that are directly related to this article, so I suggest you read them before continuing with this article.  If you haven’t read them yet, check them out.  Go ahead.  I’ll wait.

At this point, I’m trusting that you understand at least some of the principles behind good writing and design.  (If you don’t, and you didn’t read those previous articles, shame on you.)  Many, if not all, of them come into play when talking about talking to a non-technical audience.

Giving (and taking) instructions is hard

Let’s talk about that initial tie instruction paragraph for a moment.

This is a demo I use in two of my presentations.  I ask for a volunteer, preferably someone who does not know how to tie a tie.  I hand him or her a tie, and give that person simple instructions: “put it on.”  Of course, if the person doesn’t know how to put on a tie, he or she is likely to struggle doing so.

At that point, I get the rest of the audience involved.  My instructions to the rest of the group: “you folks are the help desk.  Tell this person how to put on the tie!”

I’ve done this demo to varying degrees of success.  In some cases, the audience does a very good job of explaining how to tie the tie, and it ends up looking pretty good.  I’ve also seen demos where my volunteer looks like he or she tried to tie the tie using only one hand, two fingers, and blindfolded.

The point of this exercise is to demonstrate that giving and receiving direction is difficult.  A lot of people mock tech writers, thinking that writing step-by-step instructions is no big deal.  But after putting people through this exercise, they usually end up singing a different tune.

Be patient!

When you’re talking to a non-technical audience, patience is a vital virtue.  People can be intimidated by technology, and lack of patience on your part will only do more to add to their discomfort.  Bear in mind that your audience is not as tech-savvy as you are, and will likely not have a grasp of technological concepts.

Any time you try to do a task you’ve never done before, how do you feel?  Most likely, you’re going to be at least a little nervous.  These people are likely to feel the same way.  Telling them to “click Enter” might as well be telling them to hit the gas pedal while they’re blindfolded.

Speaking of clicking Enter, don’t take for granted that people might not know what some technologies are.  I’ve heard stories of people using mice to different degrees, including using them as foot pedals and holding them up to the screen.  (And by the way, I’m sure you’ve heard the joke about not being able to find the “any” key.  I can tell you from firsthand experience that those are not jokes — the stories are true!)

What you see may not be what the audience sees

I’m sure you’ve seen the classic image below.

rubingestalt

What did you see first: a vase or two faces?  Perspectives matter, and it happens all the time when trying to explain technical concepts.  Don’t assume that your audience sees the same thing that you are.  Even if you and your audience are looking at the same screen, what you and your audience see might not be the same thing.

Having said that…

A picture is worth a thousand words.

Very early in my professional career, I was tasked with writing a document for the nighttime support staff, explaining how to support a WORM drive.  When a customer requested data from an optical platter that was not in the drive, the user needed to insert the new platter into the drive.  I could have written an instruction saying that the A side had to be up, with the A label on the left edge, and the disk slide facing away from you as you put it in the drive.

Instead, I opened my very primitive paint program and drew something similar to this:

disk

Suddenly, the instructions were clear.  The document was successful, and the operators were able to follow it to perfection.

However, be careful — there is a wrong way to use illustrations!  Imagine, for example, that you’re trying to find a Little Caesar’s Pizza or a Home Depot.  You find a site that has a map.  The problem is, the map is an image that’s zoomed in (with no way to expand the map).  The image looks like this:

map

Tell me, on what street are these places?  For that matter, in what city, state, or even country are these located?  There’s no way to tell, because there is absolutely no point of reference or context to this illustration.  A picture might be worth a thousand words, but if you’re not careful, it could be worth exactly zero words.

Use analogies

I once sat in on a SQL Saturday presentation by Thomas Grohser where he was talking about SQL data storage systems and data access.  I’ll admit that I had a hard time following some of what he was saying, until he gave the following analogy:

“Imagine you get on an elevator with ten people.  Each person presses a different button.  Now imagine that the elevator has to go to every floor in the order that the buttons were pushed!

Suddenly, Thomas’s concept was crystal clear!

Another time, I was speaking to a co-worker who had tried to explain to someone that she was trying to store more data on a disk than there was space on the disk.  (This person did not understand that data takes up disk space.)  I told him, “you should’ve said that you can’t put ten pounds of stuff* into a five pound bag!”

(*Okay, I didn’t say “stuff!”)

The moral of the story is that analogies are highly effective in communicating concepts.  If you can effectively explain a concept using an analogy (note: make sure the analogy you’re using is business-appropriate), then go ahead and do so.

KISS!  KISS!  KISS!!!

No, I don’t mean hanging out with your sweetheart.

Make sure you follow the KISS principle: KEEP IT SIMPLE, STUPID!

Technical instructions need to be kept simple.  A lot of technologists don’t understand that reading is work!  It takes work to read and comprehend a paragraph.  What if a set of instructions needs to be understood quickly?  If a person needs to take a minute to figure out what is being said, that’s a minute that was just wasted.

Generally, the rule of thumb I use is, if it takes more than a few seconds for a reader to understand my instruction, then my instruction has failed.  Don’t make the reader have to work.

Realize that this will not happen overnight

Now that I’ve gone through some of the suggestions for talking to non-technical people, understand that not everyone has the ability to convey technical information in a manner that can be understood, and being able to do so won’t happen overnight.  Like everything else, it takes time and practice to get that skill down.

In any case, hopefully, these tips will help you become a better technical communicator.  In the long run, this ability will enhance your skill set — not just as a communicator, but as a technologist as well.

Advertisements

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.

My first featured podcast!

My podcast is now online!  Check it out!

Document maintenance is critical

I had two appointments this past week.  The first was one for my car to get my oil change and to make sure everything was in good working order (it was).  A couple of days later, I had a dentist appointment.  It was a routine cleaning (I also had a procedure done — one that I’d been putting off for a while).  While the two appointments were for different reasons, they both served the same purpose: to perform maintenance.

Just about everything, especially anything mechanical, is going to break down over time.  Maintenance ensures that things remain in good working order.  But when we think about maintenance, we usually think about car repair, roadwork, furnaces, and water heaters.

I’m sure many people in tech industries consider periodic hardware and software maintenance.  Hardware can break down.  Drives crash occasionally.  CPUs are upgraded to keep pace with emerging technology and to support software.  Speaking of software, bug fixes are constantly made.  There’s also the matter of security; virus software definitions are constantly updated, and operating system patches are distributed to ensure computers are safe.

But here’s another question: when was the last time you maintained your documentation?  Does your documentation, which was written for, say, Version 1.0, reflect what is in Version 2.0?

The trouble with documentation, even the best-written documentation, is that it can become obsolete over time.  Processes and systems change.  Interfaces are redesigned.  Steps become more efficient, or in some cases, even eliminated.  Change happens.  It’s one of the sure things in life.  Documentation should also change as well.  How often has your help desk received calls from frustrated customers saying things like, “your instructions say ‘press the red button,’ but there’s no red button on the interface!”

If your product changes — and it inevitably will — your instructions should change with it.  It’s important that systems are maintained.  Your documentation should be maintained as well.

My first podcast interview!

About a week ago, I received an email from Carlos Chacon of SQL Data Partners inviting me to take part in a podcast.  This was my first such request, and I jumped on the opportunity.

The podcast recording took place last night.  My topic was along the lines of “writing and communication: why it matters to data professionals.”  It was a lot of fun, and I very much enjoyed talking to Carlos and his partner, Steve.

The podcast should air sometime in March.  It will be posted on their ‘blog.  When it does, I’ll make sure that I post a link to it!

Why design matters

“A user interface is like a joke. If you have to explain it, it’s not that good.”
— unknown

There are two elevators in the building where I work, including one that doubles as a freight elevator — it has front and back doors for access.  This particular elevator has a bank of buttons shown in the photo below.  The buttons for the rear door are denoted by the “R” next to the floor number.

elevator_buttons

Here’s why these buttons frustrate me.  Quickly, tell me which open and close door buttons work for the front and rear doors!  Yeah, I can’t tell, either!  You would think that the upper buttons control the front and the lower ones control the rear, but you can’t discern that from the way it’s laid out (and I’ve found that it isn’t necessarily the case).  I have had multiple occasions where I’ve tried to hold the door open for someone rushing to catch the elevator, and ended up hitting the wrong button.

Had these buttons been properly laid out, the open and close door buttons would both been placed under each respective door button column — i.e. the open and close door buttons that control the rear door should have been placed under the buttons marked “R,” which would clearly indicate that those buttons are used for the rear door.  That would make sense, wouldn’t it?

Raise your hand if you’ve ever been frustrated by a product simply because the user interface was poorly designed.  I would expect every hand in the room to be up.

Don Norman, an academic researcher considered to be an expert in usability design, talks about this phenomenon in his book, The Design of Everyday Things (disclosure: at the time of this article, I have not read this book — yet).  One very common example involves doors.  How many times have you come across a door with a handle, leading you to think you need to pull it to open the door?  Yet when you try it, it turns out that you need to push, not pull it, to open.  It’s extremely frustrating, and it happens more often than you think — so often, in fact, that it even has a name: a Norman door.

If you don’t think good design isn’t a big deal, there have been documented cases where poorly designed interfaces resulted in a significant loss of life.  I did a Google search for “disasters resulting from bad design,” and the results were startling.

This subject is of particular interest to me, speaking as someone whose job revolves extensively around technical communication, technical writing, and front-end development.  In my line of work, design and layout are a big deal.  I have seen many examples on the job of horrible documentation and bad interfaces — and poor design was a major factor.  I mentioned in an earlier article that I came across illustrations in a company document that were completely useless.  Pictures may be worth a thousand words, but if they’re not properly used — and yes, there is a wrong way to use them — they can be worth exactly zero words.  Likewise, one of my current projects is working on how to make an internal corporate social network work for my department.  I’ve discovered that I have a love/hate relationship with it; while I have no problem with the concept, the execution leaves a lot to be desired.  One of the most basic questions I have with this system which it fails to answer — and which should only be answered by the interface design without having to look up instructions — is, “where am I supposed to begin?!?”

Interfaces exist in just about every facet of our lives, including, but not limited to, application front-ends.  Good sensible design must be involved in creating them.  More often than not, they’re just “thrown together” without any thought as to how they should be laid out and how they are to be used.  The consequences of poor design abound.  In the best of cases, such as with Norman doors, they are just annoying.  But in the worst cases, they can have disastrous and fatal results.

Writing blind

“Life is like a sewer.  What you get out of it depends on what you put into it.”
— unknown

As a technical writer, one thing I often request is access to the product — whether it’s a web site, application, device, tool, etc. — that I’m writing about.  In order for me to write something about a product, I need to know what the product is, how it works, and how to use it.

Unlike, say, a novelist or a creative writer, technical writing topics usually do not originate from the writer, but from something or someone else, such as a process, procedure, or product.  In order for the writer to produce a good, quality document, he or she must know about it — what it is, why it’s significant, what it looks like, how to use it, potential issues, and so on.

What happens, however, when the only resource you have is someone else’s description?  Moreso, what happens when that person is (by his or her own admission) not a writer?  (There’s a reason why this person gave you this project in the first place.)  I recently worked on a small side project that reminded me just how important this is.  Granted, it was only a small and minor project, but it did remind me about just how critical it is for a writer to understand the subject.

Imagine the following situation: you need to add more windshield washer fluid to your car.  You open the hood and see different caps.  You know there are caps for washer fluid, engine coolant, oil, and so on.  However, they are not clearly marked (as far as you can see), and you don’t know which one is which.  Opening the wrong cap and filling it with the wrong fluid will damage your car.  You call a friend who tells you to look for a plastic reservoir filled with blue liquid.  Trouble is, there are two of them (one is washer fluid, the other is coolant).  Your friend tells you to look for something that looks like a windshield on the cap.  Okay, you see something that looks like it might be a window with a wiper going across it.  That’s it.

Sound frustrating?  These are the kinds of situations that technical writers and communicators deal with regularly and on a much larger scale.  In order to write a technical document, the writer must have a source of good data — whether it’s hands-on experience, pictures, data graphs, good descriptions, etc. — in order to write a quality document.  A bad or inaccurate source of data will often result in a bad document.

Developers, coders, and data professionals have a name for this kind of situation: garbage in, garbage out.  In order for data to be processed into information (I won’t get into it now, but there is a difference between data and information — that’s another topic for another time), you need to have good data to start.  Bad data results in bad and inaccurate information.

Writers cannot read minds.  Unless a subject matter expert (SME) can properly convey his or her idea (and it almost never happens on the first go-around), it might take several iterations and lots of SME-writer interaction before the draft is correct.

Professional chefs have a term for ensuring everything is set up and in place before cooking: mise en place (pronounced “MEES-in-plahs”).  While the technology sector does not use the same terminology, the principle still applies: make sure things are in place and ideas are properly conveyed before information processing (including documentation) can occur.  Otherwise, trash at the beginning of the process will likely result in trash at the end.