For those of you who produce documentation, how often have you sent your documents out into the real world, only to have it returned to say it’s all wrong? Or have you ever received feedback saying things like “this is difficult to read,” “I can’t follow this,” and so on?
One of my most frustrating aspects of technical writing is any time — every time — that I ask people to review what I write, my request goes ignored. As I’ve written before about the nature of documentation, requests for document review are often met with indifference and disrespect. A lot of people just don’t think it’s important. It is critically important. I don’t always know about the subject that I’m writing, and I’m often at the mercy of subject matter experts (SMEs) who know more about the subject than I do.
It’s not just the subject matter, either. I’m the first to admit that I’m a grammar snob, but I’m also not perfect, either (I was not an English major, after all). Many a time have I confused “who” and “whom,” ended a sentence with a preposition, used an apostrophe-S for a possessive, forgotten to put “I before E,” and so on. Likewise, I try my best to design documentation for better readability, but I also realize that there’s always room for improvement, and it often takes another set of eyes to provide a way to make something better than never occurred to me.
I’ve argued before that documentation needs to be treated like software. Like software, documentation has a life cycle. It needs to be maintained. And as such, it needs to be tested. Documentation, like software, will have bugs that need to be addressed.
It also isn’t just a matter of reading a document and saying “yeah, this looks good.” User testing should also be a part of it. If you’re writing step-by-step instructions, how will you know if they’re accurate? Back when I was a grad student at RPI, one of my writing projects included user testing as part of the project. I wrote a set of instructions for a procedure in my office (the document served a dual purpose for me — not only was I getting graded for it, I was also contributing to my workplace). To test it, I asked one of my co-workers to follow it as she went through the procedure I’d documented. She caught issues with my steps that I never would have caught on my own. From that user testing, I corrected the issues and made the document even better.
As a technical writer, I expect — and demand — people to review, test, and scrutinize what I produce. I demand excellence from myself. In order to achieve excellence, I need other people to review what I do. And I want to know that what I’m producing is of good quality and factually accurate. Without that critical feedback, I’ll likely not know whether or not I’m doing my job.