Technical Writing Rule #13

another in a series of rules that all technical writes must know

Engineers are wrong, a lot of the time. Don't assume that what they tell you is truth UNLESS they are the primary person responsible for the discrete piece of code or equipment you are inquiring on.

A really good technical writer will know the system to be documented holistically, and should be able to notice all inconsistencies.

action or subject

Pretend you are a user for a second, and not the technical writer. When you read a manual, do you, personally, want an action/task or subject oriented arrangement?

Over and over it is drilled into our little TW heads that everything should be action-oriented because the users are reading your prose to get something done for their job.

Maybe this is an overy-geeky opinion, maybe it's just me, but I don't think this is a fair assumption. I'm reading about a technology that I'm interested in and have background in. I don't really want someone to tell me how to do my job, I want someone to tell me the theory, all pitfalls noted and let me piece together my own procedure.

I can't be all alone here.

value vs reality!

via C-Net's article about Nicholas Negroponte's commentary re: ongoing $100 Laptop for developing nations:

Once children have the laptops, they'll teach themselves, he predicted, making teacher training beside the point. "Teachers teach the kids? Give me a break," he said. "Give any kid an electronic game and the first thing they do is throw away the manual and the second thing they do is use it."

he's right, you know...

The Least Appreciated Mentality

Many of us in the technical communications field approach our work with a chip on our shoulders. The prevailing attitude is that of constantly trying to prove our work's worth. It's the classic: "the manual is important, no really, it is!" sentiment.

Well of course it is, and anyone who says otherwise is a fool. Period, end of story. If you ask any executive or (real) engineering manager what their opinion is of technical documentation, they would probably reply that it’s just one of the necessary steps involved in creating a solid software/hardware product.

But why does the technical communicator live his or her life in constant fear that no one gives a shit about the great documents he or she writes? I have come up with 6 reasons why so many technical writers are defensive about the value of their work. Feel free to add or criticize.

• Unsung hero - It's a certain kind of person who is comfortable with doing a task and not getting much credit. You really need to be of this temperament. After all, the developers of software/hardware are most prominently seen as the primary creators, and even before that it's product management who takes all the credit. I think for this, and so many other analogies, Technical Writers fall into the same category as the QA team. In fact, the TW's role is more visible than a QA person's role in product development. But at the end of the day, both must know to themselves that their work is crucial in delivering that high-quality product.
• False Truth – It’s common to say that no one reads the manual. But, we all know this isn't true. People just don't refer to documentation first. More pointedly, they don't read the manual as they read a book. People refer to the manual for the singular task they need help with. That's all it takes for your writing to return value.
• Low Positive Feedback - What do you want, a cookie? Seriously, no feedback is a good thing. People are more apt to tell you what they think when something is wrong, not when it's right. That's a constant in life actually. If you want positive feedback, go into some customer-service oriented field.
• Content is King - This is a controversial one, but the more specialized the field, the more often it is that the manual does not get the resources or time to include all of the necessary information. TWs put their efforts into things other than the content, like layout and design. The end result is that the information a user requires is missing or insufficient. When problems like this surface, they enforce the notion that the manual is crap.
• Nitpicking Users / High Negative Feedback - Everyone is a critic, and it’s easy for people to attack what's missing and what's wrong. After all, everyone took a composition class in college, so just about ever reader has some basis for critiquing your work. OTOH, you probably can't fire back at a colleague's work because you don't know a thing about RTOS design. It's annoying, and raising the ire of a technical writer often opens the engineer up to a relentless critique of their comma usage in emails and design docs. Don't go down this path :)
• Self Evident software - Since GUI based software is the norm these days, more times than not, it's easy to figure out the basics of an application. For a good number of tasks, documentation isn't quite necessary, it's more of a formality. And since we start at the beginning, our first work is less valued than nailing down the details.