Uncharted Waters

Mar 12 2015   10:17AM GMT

Even Technical Writing Deserves A Real Voice

Michael Larsen Michael Larsen Profile: Michael Larsen

One of my daily frustrations is reading through technical documentation. Sometimes it is for my own product (and thus, internal). Much of the time, it also involves materials on the web, i.e. researching an open source tool. There is a brisk trade in the book market today for technology titles, especially those related to tools, to help us make sense of what we use each day. A lot the technical documentation available is written by programmers or engineers. I don’t mean to criticize, but the fact is, much of what is written is, at best, challenging to understand.

I am often called upon to write technical documentation, so I find that I become the person I complain about. It’s easy to put commands or instructions together as though it were a script, and leave it as is. After all, the people who will be reading my docs are smart people. They’ll figure it out, right?

A technical documentation template example

Let’s move beyond the template, and give our technical documents a real voice.

Does this sound familiar? Due to time constraints, or the need to move on to other tasks, I have often been guilty of this. I know who is coming along to read my documents. I assume they will be like me, with my understanding. The problem is, I don’t know what knowledge or skills they bring to the task. Things I take for granted, they may not know or may not describe the same way. In short, I may, and likely will, prove to be the documentation writer that I am complaining about. What to do?

One of the best approaches I’ve learned comes from San Francisco Bay Area writer Anne Lamotte. Her admonition is that every writer needs to allow themselves the ability to create a “totally [lousy] first draft” (she uses another word, but I think the point is clear). By giving ourselves this freedom to not be perfect right out of the gate, we can push out a first draft, and then get feedback. This is important, as we want to make sure what we are writing will make sense to others.

That’s great if we have multiple people who understand what we are doing, but what if we are the first to do it? What if review is impractical, or even impossible? In that case, I use a self editing process. I aim to give anything I write twenty-four hours distance. By doing this, when I reread it, it feels as though it were the first time. This makes it easier to cut or modify what I’ve written.

I am also a strong believer in performing audible reads of technical documents, often recording what I say. This lets me catch if I am making grammatical errors, as well as to see if the flow of my conversation makes sense. Again, the act of giving myself space after a recording or a read-through helps me find errors in flow or delivery. If on a later listen, I have trouble understanding what I’ve said, what are the chances anyone who needs to read my document will fare any better?

Stencils to shape letters.

Sometimes making things clear requires going back to the basics.

These steps are, of course, not foolproof. They will not guarantee that what I write will be fully understood by later readers. However, they improve the odds considerably that what I have written will be understandable, repeatable, and effective.

2  Comments on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.
  • FTClark

    Valuable post...

    I have also discovered that returning to a project after a period of time is a great tool.

    A tool I find useful on the first or later pass is to visualize someone else reading or hearing my material and attempt to get inside their head and see/hear from their perspective. Even better, when practical, if I can find a real person to read to and watch their facial expression and experience their perspective.

    1,280 pointsBadges:
  • Michael Larsen
    Agreed, it is always a plus if you can get someone else to be a stand-in to help you see if what you are saying makes sense. Barring that, getting into someone else's head would be the next best thing (persona based writing ;) ).
    6,160 pointsBadges:

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: