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?
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?
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.