Musings from a frustrated technical writer

(Source: dilbert.com)

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.

Advertisements

Time is Precious

My friend, Steve Jones, wrote this article, and it is well worth the read (most of his articles are), even if you’re not a technology professional. If you care about your craft — no matter what it is — set aside a little bit of time to improve upon it.

Voice of the DBA

I’ll hear people constantly say they don’t have time to work on their career. They can’t attend a UG meeting to network. They can’t spare a minute to go through a Stairway Series. They have family commitments, kids, hobbies, volunteer activities, spiritual needs, and more. That’s not even counting all the work they need to get done as a part of their job. When can they spend time on R or Machine Learning or CosmosDB or anything else?

I get it. My life is chaotic as well, with deadlines and a pile of work that never goes away. I sometimes dread travel and vacation because that means my work piles up on either side of those events. This is on top of commitments to keep up on chores at home (I have cooking and laundry), fix things at the ranch, spend time with kids, get date nights with my…

View original post 440 more words

Blind spots

“All I want from tomorrow is to get it better than today…”
— Bruce Hornsby (or Huey Lewis — whomever you prefer)

“You’re only human; you’re allowed to make your share of mistakes…”
— Billy Joel

One of my favorite books is The Sword of Shannara by Terry Brooks.  For the benefit of those of you who’ve never read it (spoiler alert: if you’ve never read it and want to, I suggest you stop reading this paragraph and move to the next one, because what I’m about to say doesn’t get revealed until near the end of the book), the book involves a magic sword that has the ability to reveal truth.  When the sword’s magic is invoked, both the wielder and the recipient are forced to confront the truth.

There are many times that I wish I had a Sword of Shannara.  I can think of many people who would benefit from its magical power.  And I put myself at the top of that list.

An incident that occurred last night served to remind me of the blind spots that I have.  I don’t care to talk about the incident (the details aren’t important here, anyway), except that I felt as though I’d taken a big step backwards.  It’s not the first time that I’ve taken a step back, and as much as I try to avoid it, I suspect that it will likely not be the last.

We all have blind spots; it’s a part of being human.  More often than not, we aren’t aware that those blind spots are there — hey, there’s a reason why they’re called “blind” spots.  There is no magic sword to reveal those blind spots.  The best mirror we have for those blind spots is each other, in how we behave and react around one another.  If someone is smiling, laughing, or nodding his or her head around you, you’re probably doing something right.  If that person is frowning, yelling, or criticizing, then probably not.

As much as we try to do our best, inevitably, we will stumble somewhere down the line.  I admit that I’m probably still dwelling on it — I probably wouldn’t be writing this article, otherwise.  I’ll eventually get over it.  All we can do is to recognize our blind spots — once we recognize that they’re there — keep an open mind, learn from our mistakes, and keep moving forward.

To be a more likable speaker

This afternoon, this article about being a likable speaker crossed my inbox.  It’s a quick and easy read, and I thought people who do public speaking or present regularly (as I do for SQL Saturday) would find this of interest.  I thought it was worth a share.

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

So, what’s in it for me… I mean, the company?

The Facebook “Your Memories” feature can sometimes be an interesting thing.  Yesterday, this memory from four years ago came up on my Facebook feed, and it’s one I want to share.

I think I’ve discovered the secret to great interviews — and I’m sharing this for the benefit of other job seekers like me.

Based on some resources that I’ve read (including “What Color Is Your Parachute?”), most job seekers go to an interview wanting to know, “what’s in it for me?” What they *should* be doing is asking the company, “what’s in it for them?” In other words, ask the company what they want and what you can do to fulfill it. Sell yourself on the precept of what value you bring to the company.

For the past two days, I’ve gone into interviews with this mindset, and it has served me well. It’s one of the reasons why I feel like I aced yesterday’s interview. Also, during this morning’s interview, I asked the question, “what are intergroup dynamics like? What other groups do you work with, how are the relationships, and what can I do to improve them?” When I asked that, I saw nods around the room that said, “that’s a good question!”

It’s too soon to say whether or not I landed either job, but I feel like I interviewed well, and I feel like I have a fighting chance.

Ever since I had this revelation four years ago, I’ve used this approach in every single job interview.  I won’t say that I aced every single job interview — I didn’t — but this mindset has made for better interviewing on my part.

Let me back up a little before I delve into this further.  It’s been often said that you should never not ask questions at a job interview.  Asking questions demonstrates that you’re interested in the job.  I’ve heard stories where a job candidate completely blew the interview simply because he or she did not ask any questions.  Not asking questions demonstrates that you’re indifferent toward the company or the job.

That said, it’s also important to ask the right questions.  Never ask about salary or benefits (as a general rule, I believe that you should never talk about salary or benefits, unless the interviewer brings it up).  If at all possible, try to avoid questions that ask, “what’s in it for me.”  Instead, ask questions that demonstrate, “how can I help you.”

Employers are nearly always looking for value, and their employees are no exception.  When interviewing potential candidates, they look to see what kind of value the candidates offer.  For me, I go to every job interview with a number of questions that I’ve formulated in advance — questions that demonstrate I’m interested, and I want to help.  For example, one question I always ask is, “what issues does the company or organization face, and how can I help address them?”  I’m asking what I can do for them.  It shows that I’m interested, and it shows that I’m willing to lend a hand.

For your reference, I found this information in my local library.  A couple of books I would recommend include the most recent edition of What Color Is Your Parachute? and Best Questions to Ask On Your Interview.  Among other things, these books provide ideas for questions for you to take with you to the interview.  Much of this information is also available on the internet; do a search and see what you can find.

I would also consider attending seminars and conferences, if you are able to do so.  For example, Thomas Grohser, one of my friends on the SQL Saturday speaker’s circuit, has a presentation called “Why candidates fail the job interview in the first minute.”  I’ve sat in on his presentation, and I would recommend it to any job seeker.

I won’t say that this mindset guarantees that you’ll get the job, but it will increase your chances.  This approach shows the interviewer that you’re interested, and you can add value to the organization.

Best of luck to you in your interview.

Reinventing yourself

If there’s one thing I’ve managed to develop throughout my professional life, it’s my ability to adjust to my environment.  I’ve practically made a career out of it.  It’s an ability that has managed to keep me sane in tough situations, not to mention that it has enabled me to extend my shelf life long after my role, whether it’s because of an organization’s changing needs or my skill set no longer fits, has become obsolete.

A ballplayer with a long career (yes, here I go again with the baseball analogies) is usually able to do so by developing a new strength after an old one is no longer effective.  For example, pitchers such as C.C. Sabathia or Bartolo Colon have reinvented themselves as finesse pitchers who get batters out using guile and precision, long after their fastballs are no longer effective.  Likewise, a professional who is having difficulty keeping up with modern trends or technology may need to reinvent him or herself in order to remain relevant in the marketplace.

My recent unemployment forced me to take stock of where I am in my career and where I want to be going.  Even before my (now-former) employer let me go, I’d been asking myself some hard questions about who I was.  I had been struggling as a developer, which was making me question whether or not it was what I should — or even wanted — to be doing.  At the same time, I also considered my strengths.  What was I good at doing?  Were these strengths marketable?  Were they skills that I could offer to an organization?  Would I enjoy a position that took advantage of these strengths?

For me, personally, I discovered — or, more accurately, re-discovered — that my strengths were in writing and communication, not software development.  This revelation made me realize several things.  While I enjoyed doing development work, I found that I wasn’t passionate about it.  I was, however, passionate about writing and documentation — to the point that I began steering myself in that direction.  I became openly critical about my company’s documentation (and, in many cases, the lack of).  My SQL Saturday presentations have all been based on writing and communication.  Even in my current job search, my focus has been on positions that emphasize writing and communication over hardcore technical skills.  Having said that, I am also not discounting my technical background; my ideal position is one that takes advantage of that background.  While I am looking for something that focuses on communication, I am looking at my technical background to supplement that skill.

At this point in time, whether or not this strategy lands me a new position remains to be seen.  However, I’ve made some observations.  First, I’ve noticed that prospective employers appear to be more receptive to my approach.  I seem to be getting more and better prospective opportunities, and they are coming quickly.  Second, I’ve noticed that, in conversations and interviews, I am much more confident and assertive.  Third, I’m much more focused in my search — in contrast to job searches in years past, where I would apply to anything and everything that even remotely sounded like a position I could fill.  Finally, as strange as it may seem, I’m finding that I’m actually having more fun with this process.

It’s often been said that when a door closes, another opens.  If a current position or career isn’t working for you, it might be time to take stock and reinvent yourself.  You might discover a new mindset and a new motivation.  You might discover a new passion.  You might even find that reinventing yourself results in a new career path — one that is more satisfying and rewarding than you had ever previously believed.