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!

What are effective communication skills?

I cam across this article on Grammarly, and I thought it spoke volumes — enough that I’m sharing it in this ‘blog article.  Read and enjoy!

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.


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.

Musings from a frustrated technical writer


As someone who has professional technical writing experience, I am often asked to edit or rewrite documents written by other technical professionals such as developers, IT personnel, managers, and so on.  The ability to create good functional instructional documents is a skill — just like the ability to write good object-oriented and structured code, to design good database table structures, or to properly articulate a difficult run in a piece of music.

Unfortunately, too many people don’t understand that, which is baffling to me.  I’ve seen instances where technicians threw together their poorly organized (and I use that word loosely), badly written notes into a Word document and sent it to a customer, saying “here’s the documentation.”  More often than not, technical writers are disrespected, looked down upon, and are often the first ones cut when budget cuts come into play.  Too many organization and departments say, “documentation is not a priority.”

The problem is, documentation is and must be a priority.

Not everyone can write.  I understand that.  By no means do I intend this article to make technical writers out of people; after all, people do this for a living, and a good chunk of my master’s degree revolves around its principles.  If an entire degree program focuses on documentation and communication principles, there is no way I can cover it all in a single article.  Rather, I’m looking to raise awareness of the documentation skill set and how people can improve the process.  My hope is that this article makes life easier for all professionals.

So with that, here are some tips that I’ve established, through many years and projects of painful experience.

Technical documents come in all different flavors, shapes, and sizes.  I’ve often asked people the first thing that comes to their mind when I say “technical writing.”  I’d guess that, about 95% of the time, they answer either “step-by-step instructions,” “manuals,” or something similar.  I’ll often respond: “what about flowcharts, online help, diagrams, org charts, admin guides, user guides, web sites, UX/UI guidelines, ‘blogs, application menus, and so on” (and maybe even a few other things I haven’t thought of).

Know your audience: This may very well be Rule #1 when writing documentation.  Above all, you need to know who will be reading your document.

People will have different levels of expertise.  They might know some terms, but not know others.  The trick is being able to talk to them at their level, while at the same time, not insulting their intelligence.

Don’t tell me how to build the clock!  Just tell me what time it is!  I once worked for a CTO who was very fond of that quote, but it makes a lot of sense.  Far too often, inexperienced “writers” feel like they need to explain every single tidbit of detail when they’re trying to convey an idea.  Not only is this unnecessary, it’s counterproductive.  Bogging information down with too much detail where it’s not needed makes a document nearly impossible to follow.  A good technical document must be able to describe a task in as few words as possible.  This is not an easy task (and I’m amazed — and not in a good way — as to how many people think this is not a big deal).  Generally, my rule of thumb is, if an instruction cannot be understood or followed quickly and easily (generally within a few seconds, but primarily within a minute), the document has failed.

Having said that, there are times when some documents need to have every detail spelled out (a systems administration guide or reference — which isn’t necessarily meant to be followed quickly — comes to mind).  There are exceptions to every rule.

Never, EVER, assume that just because you know a term that your audience will.  Much of this goes back to knowing your audience.  Often, you need to make assumptions about people who will be reading your document.  But will those assumptions ever be 100% accurate?  I’ll bet my house that the answer is no.  Say, for example, you’re working with a teenaged college intern.  Will he or she understand acronyms and terms such as SQL, Artifactory, ETL, XML, BI, content management, UX, PaaS, and so on?  That person may know some of the terms, but not necessarily all of them.  Even I’ve come across many examples where I didn’t understand a document’s context simply because I didn’t understand the terminology.

Never assume that anything is “obvious.”  I created a generic checklist template that included a set of instructions as to how to best utilize it, and I asked my teammates to take a look at it and give me any feedback on it.  One comment I got was, “some of the instructions should be obvious.  You shouldn’t need to spell it out.”

My response: you’d be surprised.  Even I’ve scoffed at the warning on the coffee cup that said “the contents of this cup are hot” or the message on the laundry detergent that said “the gel pack should never be eaten.”  However, I’ve seen too many instances where some task was “obvious,” yet the end user found a way to use it incorrectly — often in ways that never occurred to me.  Almost anything can be misconstrued, misunderstood, or misused.  Something you think might be “obvious” might not be.

Your document needs to make sense.  Writing a step-by-step document is like writing a program.  It must follow a logical order.  Before you tell someone to walk through a door, you must first tell them to open the door.  (Yes, I realize this is a painful example of my earlier point of “don’t assume anything is obvious,” but I digress.)

You are providing guidance, NOT holding a conversation!  One of my big pet peeves in an instructional document is the use of “conversational” or “social” language.  For example: “Please look at these instructions,” “it is okay to perform this step,” “you should be able to run this,” and so on.  An instructional document is not a social network.  You are not holding a conversation or politely asking someone for a favor; you are telling them how to perform a task.  People read instructions in order to perform a task, and they are looking to your document, assuming that the author has some measure of expertise, for guidance.

On the flip side, you also don’t want to be too forceful with your language, unless the task is potentially catastrophic.

How formal should a document be?  It depends on the document.  For example, does a document require a cover page or an introduction?  Consider the following:

  • Who is your audience?
  • What kind of instructions are you writing?
  • How concise does it need to be?

The more questions your document can answer, the better.

Good grammar helps.  I am a self-admitted grammar-nazi (if you’ll excuse that politically-incorrect word).  I understand the difference between “your” and “you’re.”  I cringe every time people end plural nouns with an apostrophe-S.  And I believe that anyone who uses the word “irregardless” should be sentenced to a lifetime of hard labor.

Having said that, I understand that not everyone is a good writer.  I should also mention that English is my first language, so I’m not as well-versed regarding grammar in other languages (other than maybe German, as I struggle to remember my German classes from back in high school).  (My Korean mother is also fond of telling me about how Korean is grammatically perfect — all the rules are followed; there is no “I before E” or anything like that, but I digress.)

So why mention grammar at all?  A well-written document should be relatively easy to read.  For example, one of my presentations promotes using active, as opposed to passive, voice.  Often, I’ll ask my audience why they think that is the case.  I’ll often answer that question with another question: which sentence is easier to read?  Good grammar goes a long way in addressing that.

While we’re on the subject of easier to read…

Reading is work!*  People often fail to realize this when they write.  Technical documents, especially instructions, are meant to be followed quickly.  My usual rule-of-thumb about a set of instructions is, if it can’t be understood within a few seconds, it has failed.  But people keep insisting on including every single detail in an instruction (see my comment above about “not telling me how to build the clock”).  If a person has to put effort into understanding what you’re writing, it defeats the purpose of why you’re writing in the first place.

If you think bad writing isn’t a big deal, consider these examples (under “Poor Writing and Liability”).

(*Speaking of “reading is work,” this article is becoming longer than I expected.  If you’ve read this far, I’m impressed!)

If you’re using examples, make sure they are relevant to what you’re talking about.  I recently edited a document in which the writer talked about a configuration setting.  He included a code snippet that illustrated the configuration, which was good.  But he also included a snippet that showed how the application logged into the environment — which was not good.  What does login code have to do with the configuration?  Extraneous examples and illustrations only confuse the reader, not make it clearer.

And speaking of illustrations…

A picture is worth a thousand words…  but there IS a wrong way to use them!  I learned very early that an illustration, if done properly, can explain a task better than words ever can.  The document in question involved inserting an optical data platter into a WORM (Write Once Read Many)** device.  The platter had to be inserted in a certain way and a certain side up.  As part of the document, I drew an illustration of how the platter should be inserted.  The drawing saved me the trouble of writing descriptive text that would have likely confuse the reader.

(**This is what I mean by not assuming readers know terminology.  See what I did there?)

However, I also saw an example where an instruction in an Excel spreadsheet told the reader to “look at Figure A.”  First, the reader had to click a link to see “Figure A” (it was on a separate tab, and nowhere near the text, which forced the reader to go back and forth, which was extremely distracting).  Second, “Figure A” included a icon snippet with a part of it circled.  That was it!  There was no explanation about what it was, and because it was only a snippet, there was absolutely no point of reference as to its significance.  (Think about a Google map zoomed in to the point where all you see is the pin and a street, with no idea as to the location, city, state, or even country.)  This was a useless illustration.  It’s said that a picture is worth a thousand words, but if they’re not used properly, their worth in words can be zero.

Your document is a reflection of your organization.  I think this is especially true if documents are sent to clients or even the general public.  Let’s say you’re a customer who gets a hold of a company’s badly-written document.  What would you think of that organization?  Chances are, you’d probably have a low opinion of the company.  Would you want to do business with an organization that produces poor-quality documentation?  My guess is, probably not.

These are just some of the frustrations that I (and other writers, I’m sure) have experienced.  I could probably continue, but at this point, this article likely violates several of the tenets that I’ve espoused above.  In any case, it’s my belief that bad (or no) documentation is a recipe for disaster.  Raising awareness of document criticality can go a long way in making for a better organization.

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