Technical Writers:
A Guide for Marketing and Engineering Managers

Trying to get documentation written can be extremely frustrating. This guide is written for managers who are not technical writers, but who have been assigned the task of ensuring that the documentation happens.

What Kind of Technical Writer?

The more technical the specialty, the harder it is to find someone who can write documentation from scratch. There just aren't many writers with the necessary technical background. Most technical writers were Liberal Arts majors. Many are gifted writers, but no one can write clearly about a topic he does not understand, so their talents are not easy to bring to bear.

Technical topics can be learned, of course, and many writers are self-taught or have received training in the relevant topics. Support for this kind of common-sense approach varies wildly from company to company. In the short term, you're stuck with what you've got (though as a manager, it's your job to make the long term turn out the way you want it to).

Working With the Non-Technical Technical Writer

The technical writer should be involved in blocking out the documentation. Most technical documents have a fairly simple structure that can be settled upon without actually knowing the details of how anything works. For example, when doing chip or board documentation, I start by drawing a block diagram that shows the product from the customer's point of view. The document then has one chapter per major block, plus an introductory chapter. Material that is not shown on the block diagram, like instruction set descriptions, register descriptions, and AC/DC specifications, follow along after the one-chapter-per-block section. Procedural issues (installation, troubleshooting) don't fit on the block diagram, either, but a flow chart of what the user has to do to make the product work will serve as a second block diagram, which you treat in the same way as the first one.

There are other ways to do this. My point is that, while this is not rocket science, people often get it wrong anyway, by not attending to the fundamentals. Your technical writer ought to be of use here.

Ideally, the people in charge of the various sections of the draft should know what's expected of them, down to an almost fill-in-the-blanks level. By this I mean that the headings, tables, and diagrams should have been roughly blocked out before writing begins. By breaking down the task in this way, the draft tends to go more smoothly, and fewer items are omitted. In addition, people who are not professional writers tend to be intimidated by writing projects, and breaking them down tends to reduce the fear factor. It also gives management a list of elements that the contributors can be held accountable for, so you don't have to accept vague assurances that the draft is coming along fine. Bits and pieces will get knocked off the list if any real progress is being made.

The end-user should be kept in mind at all times. Everything in the document should help the reader to understand the product. Early in the writing cycle, it's tempting to bloat up the document by putting in lots of junk from the technical specification or other readily copied sources, or to use lots of repetition. This gives an impression of progress but doesn't help the end-user. Such bulk is rarely pruned back properly in the end, so it shouldn't be added in the first place.

Working with the Technical Technical Writer

Highly technical writers should write their own drafts whenever possible. For one thing, they hate working with other people's drafts when they are (or can become) bona fide experts themselves. Also, they tend to be more willing and less overworked than the engineers and marketers who would otherwise have to do it. Sometimes these technical writers have the skills to structure their documents with relatively little feedback from the group, and can get to work without the elaborate outlining described above. I rarely use outlining myself; just unstructured lists. But I've been doing this forever and can visualize the finished product clearly without such aids. But a detailed, structured outline is useful when there's any doubt, to keep everyone on the same page.

It is easy to starve a technical writer for information. If anything interferes with the technical writer's research, work will slow dramatically. I have seen projects where the lead engineers' time was considered so precious that the technical writers were expected to not talk to them at all. Instead, they were expected to be psychic, or reverse-engineer the product, or produce a work of fiction, or something. This always results in bad documentation, though it probably doesn't matter much -- if the engineers are isolated in this way, the project is probably mismanaged to the point of being doomed, anyway.
 

Reviews

The technical writer will edit and, unless there is a separate layout department, lay out the document in its proper form. Both editing and layout always introduce new errors, so the result should be reviewed very carefully.

Reviews rarely appear on anyone's schedule, and the most indispensible reviewers are the ones who are most overbooked, so they go through the document in a blinding rush. Of course, having employees who feel too rushed to do a good job is symptomatic of management problems: as a manager, you should work to fix this.

Documentation to be read slowly, and at least one person should check the math in all the examples and try all the procedures. When reviewing, anything you have to read twice should probably be flagged; it probably needs to be reworded for greater clarity.

New hires and anyone else you can find who hasn't read a given document before should be used as reviewers. People who have reviewed a document before are reluctant to do it again, and even if they do it willingly, their familiarity with the old version means they miss things that a newcomer wouldn't. No one is more blind to errors in a document than its author. Reading the entire documentation set from cover to cover is one of the quickest ways to bring a new team member up to speed, so it's a win-win policy.

Return to the High-Tech Technical Writing main page