Technical Writing's Big Secretby Robert PlamondonFrom time to time a manager or engineer asks me the following question: "Most technical writers don't have much technical training. How do they write documents for products they don't understand?" The answer is, "They don't. If you don't understand it, you can't explain it to someone else." The whole point of a technical document is that it tells the reader how to use a product. If the product can be used successfully by a technically unsophisticated reader, the manual can be written by an unsophisticated writer. It helps if the writer has enough background to understand the designers' technical jargon, but this isn't absolutely necessary. Someone is going to have to translate it for the layperson anyway, and it doesn't have to be the technical writer. Things get complicated when the readers will use the product in a sophisticated way. For example, a statistical software package cannot be adequately documented by someone who knows nothing about statistics. An integrated circuit cannot be documented by someone who doesn't understand circuit-board design. People sometimes assume that "being technical" is a personality trait. It isn't. Only relevant training and experience counts. I'm very technical when it comes to digital electronics, but I know nothing about biochemistry. I once had a summer job in a biochemistry lab. I learned how to run the autoclave and perform other tasks, but I never grasped what the researchers around me were trying to learn, or how their experiments achieve this. The Big SecretThe big secret in technical writing is that most of the harder documents aren't written by the technical writers at all. In fact, many "technical writers" never do any writing at all. Instead, the drafts are written by engineers or marketers. The technical writers perform editorial functions and provide publications services -- copy-editing, layout, review management, and so on.The phenomenon of technical writers who do not write is so pervasive that I once interviewed a technical writer -- a man with 15 years of experience at a prestigious high-tech company -- who was visibly startled when I told him that, in my group, we wrote documents from scratch. Job titles betray no clue about a technical writer's qualifications. Regardless of background, the title is "Technical Writer" or "Documentation Specialist" or even the vaguely Orwellian "Information Designer." But managing your documentation projects requires that you separate the sheep from the lambs. The problem is that the demand for technical writers greatly exceeds the number of technically trained people who prefer writing to other work. Non-technical folks have to be brought in to fill the demand, often college graduates with a Liberal Arts background. They are often excellent writers on their own turf, but nothing in their training prepares them for the world of high-tech. Who Writes the Draft?The draft must be written by someone who can understand the product. There is no getting around this. If you can't find a technical writer who can do it, someone on your technical staff has to. The technical competence of your technical writers determines the entire plan of attack for the documentation project. Writers who are technically competent should be given the entire documentation task, so you can free up more design resources. Ideally, the technical writer should be brought in early, so the documentation can take form well before it is released to customers. This aids both the design and the selling process. It's usually possible to have a mostly-final draft well before the product is shippable. If you don't have writers who can write the draft, the task must be assigned to someone who can. This should be planned for from the outset. Writing is difficult and slow. It cannot be done in an overworked engineer's "spare time." This requires planning and management. A technical writer should be assigned to maintain the document. My rule of thumb is that half the labor of creating a document goes into writing the rough draft, and the other half goes into smoothing it up: editing it, laying it out, correcting it, and getting it out the door. This means that the non-technical writers can still shoulder half the burden of even the most insanely technical product. Also, while writing the rough draft is painful, the series of revisions and small corrections that follows is even worse. Technical writers are used to it. Finding Technical Writers Who Are TechnicalIn the high-tech industry, there are three categories of technically inclined writers.
The Toaster TestI used to test candidates by asking them what topics should be covered in the operating manual for a toaster. At first, I thought this test was so easy it would be worthless, but it turned out that many candidates who were well-spoken in interviews had no grasp of the basics. For the record, I figure that a toaster manual ought to contain the following sections, many of which would be no more than a paragraph in the finished document: Competent technical writers can dash off something like this in a few minutes. Some can dictate one without stopping to think. But I received some efforts that were truly ghastly. Not in terms of spelling, punctuation, or sentence structure. These were perfect. It's just that none of the sentences expressed anything that a reader would have cared to know. Speaking of tests, I know some people who screen resumes and cover letters by looking for errors in punctuation and grammar, and disposing of anything that isn't 100% perfect. This is pointless. Everyone in the publishing industry knows that people are terrible at finding errors their own work; that's what reviewers and copy-editors are for. The only thing that typoes in a resume and cover letter mean is that the writer was working alone. Conclusions |