Tech Writing Tips From the LinuxPlanet Pros

I am fortunate to have some of the best professional writers in the business contributing to LinuxPlanet. Over the past few weeks I’ve written a few blog entries on how to write good documentation, because, as with virtually all industries, good tech documentation is in short supply. Whether you’re contributing something for free to your favorite FOSS project, or want to get paid for your fabulous insights, the standards for good howto writing are pretty much the same. I’ve never believed that the distinction between “amateur” and “professional” was quality; that is, that amateur means poor quality and professional = high quality. The only difference is professionals get paid.

Please don’t take this to mean that you shouldn’t even try because you think you’re not good enough. Practice makes perfect, and contributing to your favorite FOSS project is a great way to help yourself and other people. I have a lot of respect for all the thousands of volunteers who hang out in forums, write tips and howtos, contribute to Wikis, and look for ways to make useful contributions.

Tina Gasperson and Bruce Byfield, who are both busy authors that you’ve probably seen on a number of sites, have their own words of wisdom to share.

Tina says:

“Never assume. An action or step that seems obvious to you is not going
to be obvious to all your readers. That’s why you’re the expert. Be
detailed, and think through the process from the perspective of
someone with far less experience than you — not less intelligence,
though. Provide lots of details, but never talk down to your audience.
It’s a fine line between equipping them and insulting them.”

That is my own number one principle. Computers require precise commands; they are no good at interpreting vague hand-waving. Leaving out steps or not spelling out exactly what needs to be done to accomplish a particular task becomes a recipe for frustration, rather than help. There is a saying in playwriting: “If a gun appears in the first act, it must go off by the second act.” In other words, if you’re not going to do it justice, don’t mention it. One exception to this is when you start off with an introductory overview: “This application can be used to do fee, fi, fo, fum, and whatever. Today we are going to learn how to do fum.” How many times have we seen “This application can be used to do fee, fi, fo, fum, and whatever. See the man page for details.” That’s marginal even as a hint– man pages, while valuable and indispensible, are usually not good howtos. If you can’t point to a good howto, that’s an opportunity to write one.

Bruce Byfield wrote a whole huge article on the subject, 12 Tips for Writing Free Software Documentation. These are my two favorite tips:

“You must become an expert in what you are writing about: Some professional technical writers pride themselves on being specialists in communication, and feel they don’t need to know the details of what they are writing about. You can always tell manuals done by them, because they are shallow and have large gaps in them. Likewise, you can always tell this type of technical writer, because they’re despised by any developer with whom they work. The truth is that, while you don’t need to be an expert when you start documenting, if you aren’t expert by the time you’re finished, you aren’t doing the job properly.”

“Don’t worry about style: In fiction, writers often call attention to their style. By contrast, non-fiction like technical writing is not about you. Your job is to provide simple, clear prose in which you are invisible. And if that sounds boring or unchallenging, you might consider Isaac Asimov’s observation that stain glass windows have been made for over a millennium, while clear glass was a much later development. In many ways, writing simply and clearly is much harder than writing with flourishes and personality. Focus on clarity and content, and let other style considerations take care of themselves. You’ll be surprised how well they work.”

It’s mind-boggling that the first one even needs to be said, but I doubt that I need to explain how sadly deficient most computer tech writing is. Tech writing is teaching, and you can’t teach what you don’t understand. Even more valuable are the tips, tricks, and workarounds that come with experience.

My own tip is to narrow your scope. Think small. It’s tempting to try to write the world in one article, but you can’t do that. Dish out nice complete bite-sized chunks. Then over time you will build a solid body of work that is beneficial to your readers, and you can look back on with pride. And probably use as a reference for your own needs.

One more tip is leave your ego at the door. It’s no fun to be corrected, and a lot of readers aren’t real tactful about your mistakes. But if they took the trouble to tell you about it and provided a correct solution, accept it graciously.

References

Tips For Documentation Writers (This Means You Too, Ace Coders)
More Tips For Documentation Writers (You Too, Ace Coders)
Yet More Tips For Documentation Writers (Writing For Money!)

Tina Gasperson was one of the original staff reporters for
Newsforge.com, the first “online newspaper of record” for the Open
Source IT industry. She’s been writing about FLOSS for business since
1999.