A Process for Writing Technical Documents

Although every technical document is unique, in most of your writing you will likely carry out the tasks described in the Focus on Process box below.

This writing process consists of five steps: planning, drafting, revising, editing, and proofreading. The frustrating part of writing, however, is that these five steps are not linear. That is, you don’t plan the document, then check off a box and go on to drafting. At any step, you might double back to do more planning, drafting, or revising. Even when you think you’re almost done—when you’re proofreading—you still might think of something that would improve the planning. That means you’ll need to go back and rethink all five steps.

12

FOCUS ON PROCESS: Writing Technical Documents
PLANNING

  • Analyze your audience. Who are your readers? What are their attitudes and expectations? How will they use the document? See Ch. 4 for advice about analyzing your audience.

  • Analyze your purpose. After they have read the document, what do you want your readers to know or to do? See “Determining Your Purpose” in Ch. 4.

  • Generate ideas about your subject. Ask journalistic questions (who, what, when, where, why, and how), brainstorm, freewrite, talk with someone, or make clustering or branching diagrams.

  • Research additional information. See Ch. 5 for advice about researching our subject.

  • Organize and outline your document. See “Using Basic Organizational Patterns” in Ch. 6

  • Select an application, a design, and a delivery method. See Ch. 7 for advice about designing your document.

  • Devise a schedule and a budget. How much time will you need to complete each task of the project? Will you incur expenses for travel, research, or usability testing?
DRAFTING
  • Draft effectively. Get comfortable. Start with the easiest topics, and don’t stop writing to revise.

  • Use templates—carefully. Check that their design is appropriate and that they help you communicate your information effectively to your readers.

  • Use styles. Styles are like small templates that apply to the design of elements such as headings and bullet lists. They help you present the elements of your document clearly and consistently.
REVISING

Look again at your draft to see if it works. Revising by yourself and with the help of others, focus on three questions:

  • Has your understanding of your audience changed?

  • Has your understanding of your purpose changed?

  • Has your understanding of your subject changed?

If the answer to any of these questions is yes, what changes should you make to the content and style of your document? See the Writer’s Checklist in each chapter for information about what to look for when revising.
EDITING Check your revised draft to improve six aspects of your writing: grammar, punctuation, style, usage, diction (word choice), and mechanics (matters such as use of numbers and abbreviations). See Appendix, Part B, for more information about these topics.
PROOFREADING Check to make sure you have typed what you meant to type. Don’t rely on the spell-checker or the grammar-checker. They will miss some errors and flag correct words and phrases. See Appendix, Part B, for more information about proofreading.

So, when you read about how to write, remember that you are reading about a messy process that goes backward as often as it goes forward and that, most likely, ends only when you run out of time.

13

Later chapters will discuss how to vary this basic process in writing various applications such as proposals, reports, and descriptions. The Focus on Process boxes at the beginning of various chapters will highlight important steps in this process for each application.

Should you use the process described here? If you don’t already have a process that works for you, yes. But your goal should be to devise a process that enables you to write effective documents (that is, documents that accomplish what you want them to) efficiently (without taking more time than necessary).

As you backtrack, you will have one eye on the clock, because the deadline is sneaking up on you. That’s the way it is for all writers. A technical writer stops working on a user manual because she has to get it off to the print shop. An engineer stops working on a set of slides for a conference presentation because it’s time to head for the airport.