Technical Writing Guide--The Writing Process: Achieving Speed and Quality

HOME

All writers want to write quickly and well. If there were magic pills to create good writing on demand, they would outsell aspirin. Though we have no prose-producing pills, we do have simple techniques for dramatically increasing the speed and quality of your on-the-job writing. This Section presents techniques to improve the writing process.

The "writing process” can be defined as the steps you follow to complete a successful writing project. Process is indeed the key to good writing because it separates activity into manageable stages, each of which includes specific goals. To introduce you to the writing process, this Section has three main sections:

-- Definition of Technical Writing—giving basic information about purpose, writers, and readers in technical writing

-- Nine Steps to Better Writing—explaining the main steps that help you plan, draft, and revise

-- Writing in Groups—providing five guidelines for collaborative writing projects

The Section ends with a writing checklist (FIG. 7) for you to use while you write.

DEFINITION OF TECHNICAL WRITING

At some point in our lives, we all do three main types of writing: academic, personal, and technical (see FIG. 1). Yet for most mortals, only technical writing remains the type that will determine our professional success.

The term technical writing includes all written communication done on the job. It originally referred only to writing done in fields of technology, engineering, and science, but it has come to mean writing done in all professions and organizations (see FIG. 2). Technical writing can be distinguished from other prose by features related to its (1) purpose, (2) writer, and (3) readers.

===

TYPE PURPOSE AUDIENCE EXAMPLE

Academic

Personal

Technical

Display knowledge

Enlighten, entertain

Get something done

Teachers or colleagues

Yourself or friends

Supervisors, subordinates, or customers

Research paper

Journal, letters

Reports

FIG. 1 Three types of writing

===

• PURPOSE: GETTING SOMETHING DONE

A practical purpose underlies all on-the-job writing. With such writing you strive to get something accomplished for your organization, for a customer, or for both. Academic writing displays knowledge, and personal writing entertains or enlightens. Although technical writing may sometimes have these goals too, its main purpose is practical—for example, to change a policy, offer a new product, or explain a procedure.

• WRITER: CONVEYING YOUR KNOWLEDGE TO THE READER

As writer, you have something to teach your readers. Usually you know more about the topic than they do—that's why you're writing to them. Readers benefit from knowledge you provide and make changes accordingly—for example, responding to problems you highlight, following recommendations you put forth, and buying products you are selling. Of course, your superior knowledge about the topic can sometimes create a problem. You must avoid talking over the heads of your readers. This challenge may be the greatest one you face as a writer.

• READERS: UNDERSTANDING THEIR DIVERSE NEEDS

Your job would be simple if each document were directed to just one reader. But actual technical writing is not that easy. Instead, a document often has many readers, with mixed technical backgrounds and with different needs. Even when a document goes to only one person, it may be read by other people later. This varied audience affects the structure and the language you select to drive home your message.

===

Correspondence: In-House or External:

• Memos to your boss and to your subordinates

• Routine letters to customers, vendors, etc.

• “Good news” letters to customers

• “Bad news” letters to customers

• Sates letters to potential customers

• Electronic mail (email) messages to coworkers or customers over a computer network

Short Reports: In-House or External:

• Analysis of a problem

• Recommendation

• Equipment evaluation

• Progress report on project or routine periodic report

• Report on the results of laboratory or field work

• Description of the results of a company trip

Long Reports: In-House or External:

• Complex problem analysis, recommendation, or equipment evaluation

• Project report on field or laboratory work

• Feasibility study

Other Documents:

• Proposal to boss for new product line

• Proposal to boss for change in procedures

• Proposal to customer to sell a product, service or idea

• Proposal to funding agency for support of research project

• Abstract or summary of technical article

• Technical article or presentation

• Operation manual or other manual

FIG. 2 Examples of technical writing

===

Thus the fabric of technical writing is formed by the special combination of three elements, as shown in FIG. 3:

1. A practical purpose

2. A writer more informed than the audience

3. Readers with diverse needs

Such writing will challenge you. The rest of this Section shows how the challenge can be met most efficiently during the planning, drafting, and revision stages of writing.

NINE STEPS TO BETTER WRITING

Most good writers are made, riot born. They work hard at perfecting the process of writing. The written product may appear effortlessly produced, but actually it results from a disciplined approach to composition. The discipline is embodied in a nine-step plan. If you follow this plan, you will learn for yourself that there is no mystery to improving the efficiency and quality of your writing.

Of the main stages of writing—planning, drafting, and revising—the first deserves the most attention but often receives the least. An extra hour spent planning can save two or three hours of rework during the drafting and revising stages. For that reason, the first seven steps concern the planning process. Then Steps 8 and 9 offer suggestions for drafting and revising your draft. (See FIG. 7 for a checklist that includes all nine steps.)

-- STEP 1: WRITE A BRIEF PURPOSE STATEMENT

A one- or two-sentence purpose statement helps get you started. It becomes the lead-in to your outline and then often becomes the first words in the document itself. Writing a purpose statement forces you to decide exactly why you are writing. It directs your effort and becomes the lens through which you view the entire writing project.

A purpose statement can begin with a simple phrase like “The purpose of this report is to ...,“ or it can include more subtle phrasing. Whatever wording you choose, strive to write a passage that clearly sets forth your intentions.

Purpose Statements

Example 1: This report presents the findings of our fieldwork at Trinity Dam, along with our recommendation that the spillway be replaced.

Example 2: The purpose of this report is to compare and contrast two computer systems being considered for Exton, Inc. The report draws conclusions about the system best suited for Exton's long-term needs.

Note that a purpose statement only indicates why you are writing. It does not present summary points such as conclusions or recommendations. It gives direction, not results, and intends only to get you started in the writing process.


FIG. 3 Technical writing triangle

-- STEP 2: CONSIDER THE OBSTACLES YOUR READERS FACE

In an ideal world, readers would anxiously await your documents and give them their undivided attention. That ideal rarely exists. In fact, you're better off making the following assumptions about the audience members.

They Are Always Interrupted

Meetings, phone calls, email, lunch, and even business trips may interrupt them as they attempt to read your document.

They Are Impatient

They want you to deliver the goods quickly and clearly. While they read, they are thinking, “What's the point?” or “So what?” or “What does this have to do with me?” This impatience may mean they will not, or cannot, read the document from beginning to end.

They Lack Your Technical Knowledge

They may not understand the technical language you use. Thus they'll feel insulted—or just plain lost—if you speak in terms they cannot understand.

Most Documents Have More Than One Reader

Readers share decision making with others. Your document may be read by persons from different levels and with different needs.

Keeping these points in mind, next you need to determine the technical levels and decision-making authority of your readers.

-- STEP 3: DETERMINE TECHNICAL LEVELS OF READERS

How much do your readers know about the subject? To answer this question, you can place most readers into one of the four categories that follow.

Category 1: Managers

Managers often are removed from the hands-on details of the topic. They need brief summaries, background information, and definitions of technical terms.

Category 2: Experts

Experts have a good understanding of the technical aspects of your topic.

They need supporting technical detail, helpful tables and figures, and even appendices of supporting information.

Category 3: Operators

Operators—such as field technicians, office workers, or members of a sales force—apply the ideas in your document to their jobs. They need (a) clear organization so that they can find sections relevant to them, (b) well- written procedures, and (c) clarity about how the document affects their jobs.

Category 4: General Readers

General readers, also known as “laypersons,” have the least amount of information on your topic and often are outside an organization—for example, citizens reading a report on the environmental impact of a factory proposed for their community. They need (a) definitions of technical terms, (b) frequent use of graphics, and (c) clear statements about how the document will affect them.

-- STEP 4: DETERMINE DECISION-MAKING LEVELS OF READERS

Your readers also can he classified by the degree to which they make decisions based on your document. During the planning process, you can classify your readers into the following three groups.

Decision-Makers

As managers, decision-makers translate your document into action. Decisions can be made by an Individual or by a committee.

Advisers

Although advisers do not make decisions themselves, they have the ear of people who do. That is, busy managers often give engineers, accountants, and others the task of analyzing technical points of a document. Final decisions may rest on recommendations that flow from this analysis.

Receivers

Some readers are not part of the decision-making process. Instead, they receive information in the document and make adjustments in their jobs accordingly.

FIG. 4 includes technical levels on the vertical axis and decision- making levels on the horizontal axis. It shows 12 basic categories of readers. Generally, the more categories that apply to any given writing project, the more challenging is your job in meeting the needs of a varied audience.


FIG. 4 Reader matrix

• STEP 5: FIND OUT WHAT DECISION-MAKERS WANT

Knowing the technical and decision-making levels of your readers is a good first step. Next you need to focus on the needs of the most important readers—those who make decisions. Three suggestions follow.

Write Down What You Know about Decision-Makers

Specifically, try to get answers to these six questions:

1. What is their educational background?

2. What is their technical literacy on the topic?

3. What main question do they want answered?

4. What main action do you want them to take?

5. What style or format do they like in documents?

6. What personality traits may affect their reading?

Talk with Colleagues Who Have Written to the Same Readers

Someone else in your organization may know the needs of the decision- makers for your document. Ask around the office to see if your colleagues can help you answer the six preceding questions.

Remember That All Readers Prefer Simplicity

When you just aren't able to find out much about the decision-makers, remember one essential point about all readers: They prefer documents to be as short and simple as possible. The popular KISS principle is the best rule to follow:

---Keep It Short and Simple---

• STEP 6: COLLECT AND DOCUMENT INFORMATION CAREFULLY

Whether you gather information yourself or get it from other sources, be careful during the research phase of the planning process. First, your reader may want to know exactly how you developed supporting data. Second, your professional reputation—and even your job—may be at risk if you err in the way you handle borrowed information. Some suggestions follow.

Record Notes Carefully

Remember the research skills you learned in high school or college? They stressed the importance of taking careful notes on any material taken from other sources. Your notes must do the following:

• Distinguish your summarizing from direct quotations

• Include exact wording of direct quotations

• Label the exact citation of the source (title, author, page, etc.)

Carefully Transfer Information from Notes to Draft

Most errors in documentation result from sloppy work. In writing drafts from notes, circle quotation marks to make obvious what you have quoted from a source. An error at this stage could produce plagiarism in the document. Plagiarism means the parading of someone else's ideas, words, or graphics as your own—whether done intentionally or unintentionally.

Use the Right Citation System

In citing borrowed information, use a documentation system most familiar to your reader. Some common systems are those endorsed by the CBE (Council of Biology Editors), APA (American Psychological Association), and MLA (Modern Language Association). Another common resource is the Chicago Manual of Style. Most reference systems now rely on parenthetical citations—that is, abbreviated references in the text of the document, as follows (Pfeiffer, p. 12). Then your sources would be listed at the end of the document, with complete information on each source. For example:

Pfeiffer, William S. Pocket Guide to Technical writing. 2nd ed. Upper Saddle River, NJ: Prentice Hall, 2001.

• STEP 7: WRITE AN OUTLINE

Completing an outline is the single best way to write both quickly and well. This section answers three main questions: (1) Why is an outline so important? (2) What should it look like? and (3) What steps should you use in writing it?

First, why is an outline so important? Here are the main reasons.

• Organization: It forces you to grapple with matters of organization at a time when it is easy to change the structure of the document—that is, be fore you have committed words to draft. As you add and delete ideas on the page and shift points from main to secondary topics, you are thinking about the best way to satisfy the readers' needs.

• Visualization: It shows you—visibly—whether you have enough sup porting information. For example, if your outline includes only one sub heading for a topic, you know that you need either to do more research or to delete the topic.

• Review: It speeds up the review process when your documents must be approved by someone else in your organization. It is much easier to make changes at this stage than later, when you have invested time in the draft. Indeed, reviewers who “sign off” on your outline are much less likely to request major changes later.


FIG. 5 The outlining process: Early stage

Second, what should an outline look like? You may remember a teacher requiring you to submit a perfectly neat outline with ideal format. Such an outline is never the first version, for we just don't think that neatly. Instead, each outline will (1) start as points spread over a page without any recognizable hierarchy, (2) evolve to a recognizable list of main and supporting points, and (3) change shape during the drafting process as you adjust points of emphasis. Outlining is messy business because it reflects the thinking you do before you write.

Third, what steps should you use in writing an outline? Follow the sequence below. FIG. 5 shows the result of the first two steps. FIG. 6 shows a later outline resulting from the third step.

= = = =

PROBLEMS AND SOLUTIONS: CURRENT CAFETERIA IN BUILDING

I. Problem #1: Poor selection

A. Only one hot meal entree each day

B. Only three sandwiches—PBJ, egg salad, and tuna

C. Only one bread—white

0. No low-fat milk products (milk, yogurt, LF cheeses, etc.)

E. No options for those with restricted diets

II. Problem #2: High prices

A. Soft drinks from $1.39 to $1.99 each

B. Hamburgers now $3.79

C. Average lunch now $7—$8

III. Problem #3: Inflexible staff

A. Unwilling to change hours to meet McDuff's flexible work schedule

B. Have not acted on suggestions

C. Not willing to cater special events in building

IV. Solution #1: End lease and make food service a McDuff department

A. Hire food service manager

B. Use students enrolled in food service management program at Maryland Shore Community College

C. Operate as nonprofit operation—just cover expenses

V. Solution #2: Hire outside restaurant to cater meals in to building

A. Higher quality likely

B. Initial interest by four nearby restaurants

1. Sally Ann's

2. Country Corner

3. Mother's Palace

4. Peaceful Platter

VI. Solution #3: Continue leasing space but change companies

A. Initial interest by three vendors

1. Excel—good regional reputation for quality

2. APG—close by and local, with best price

3. Good Food, Inc.—used by two other McDuff offices with good results

B. Current contract over in two months

C. Chance to develop contract not acceptable to current company

FIG. 6 The outlining process: Later stage

= = = =

 

Record Random Ideas Quickly

This “nonlinear” (translate—messy) process involves the free association of ideas. To stay on track, write your purpose statement at the top of the page. Then scribble down as many points as possible that relate to the topic.

Show Relationships

Surveying your page of ideas, locate the three or four main points that indicate the direction your document will take. Circle them. Then draw lines to connect these main points to their many supporting points, as shown in FIG. 5.

Draft a Final Outline

Your messy outline now must be cleaned up to make it useful to you as you write. You can either use the traditional format with Roman numerals, etc. (see FIG. 6), or you can simply use dashes and indenting to indicate out line levels. Whatever format you employ, the final outline should reflect three main features:

• Depth: Be sure the entire outline has enough support to develop the draft.

• Balance: Include adequate detail for all of your main points. When you subdivide a point, have at least two breakdowns—any object divided has at least two parts.

• Parallel Form: Give points in the same grouping the same grammatical form, both to make the outline easier to read and to ease the transition later to parallel text in the first draft. In fact, consider keeping the entire outline consistent in form—for example, by using either full sentences or fragments for your points. Fragments are preferable because they take up less space and don't lock you into sentences too early.

With outline in hand, you are ready to begin the second part of the three-part writing process—drafting.

-- STEP 8: WRITE YOUR FIRST DRAFT QUICKLY

The first draft offers you another chance to speed up the writing process. Unfortunately, this is when many writers encounter “writer's block” and slow down. What follow are suggestions for capturing time often wasted at this stage. Of course, the most important suggestion was covered in the previous step—always enter the drafting stage with a complete outline in hand.

Schedule Blocks of Drafting Time

Writing requires concentration. Close your door if you have one, head to an empty office, or write at home—j do whatever you must to keep from being interrupted for at least 30 to 60 minutes. B giving writing a priority, you will finish drafts in record time. However, if you allow every other activity to upset your drafting schedule, writing even a simple document will consume your day.

Don't Stop to Edit

Editing uses a different part of your brain than drafting does. When you stop to correct grammar or spelling errors, you derail the drafting effort. With each interruption it becomes harder and harder to regain the concentration needed to write the draft. Save editing for later.

Begin with the Easiest Section

A well-structured outline gives you the luxury of starting with almost any part of the document. Skip around if doing so allows you to write the draft more quickly.

Write Summaries Last

Summary sections—like the executive summary for a formal report— usually get written last. They require the kind of thoughtful overviews and careful wording that you can write best after you've seen where the entire document is going. Of course, you can write a summary at any time if you have a good outline. It's just that you will write the best one when you have the chance to view a completed draft of the rest of the document.

Your goal is to get words on paper quickly. Following the suggestions above will save you hours each week, days each year, and weeks over a career. The ideas are simple, but they work.

• STEP 9: REVISE IN STAGES

During revision, you must attend to matters of content, style, grammar, and mechanics. The trick to solving a variety of editing problems is to adopt a “divide-and-conquer” approach. Review the draft several times, correcting a different set of problems on each run-through. This effort to focus your attention on specific problems yields the best results. Four stages of revision follow.

Adjust and Reorganize Content

This task could be considered either the first stage of revision or the last stage of drafting. Here you expand sections that need more development, shorten some sections, and change the location of some passages.

Edit for Style

Style refers to changes that make your writing smoother, more readable, and more interesting. Here are options to consider:

• Shorten sentences

• Improve clarity—for example, by adding transitional words and by rewording passages to show the logical flow of ideas

• Change passive-voice sentences to active

• Define technical terms

• Add headings, lists, and graphics

• Replace longer words with synonyms that are shorter or easier to understand

Edit for Grammar

Grammar haunts all of us. Your head may be filled with dozens of half- remembered rules and terms from school days—comma splices, sentence fragments, subject-verb agreement, and dangling participles, to name just a few. You want to follow the rules, but you're no English teacher and certainly don't have time to become one. The answer to this dilemma is twofold:

• First, use your own knowledge or the editorial advice of another to deter mine the most common grammar errors in your writing. Focus mainly on this short list—not on all grammar errors—when you edit.

• Second, use Section B of this guide as an editing resource while you write.

Edit for Mechanics

Examples of mechanical errors include the following:

• Omitted words or phrases

• Misspelled words

• Inconsistent margins

• Wrong paging

• Nonparallel format in headings or subheadings

Word processing has made such errors less common and easier to correct. But technology also has lulled us into a false sense of security. You need to remain vigilant in spotting the potentially embarrassing errors that may have worked their way into your draft.

In summary, these nine steps comprise a strategy for writing every kind of on-the-job document. They require you to apply the same degree of organization to writing that you apply to other parts of your job. After all, how much of your average day do you spend writing? 20%? 30%? 50%? Using a disciplined method will help you use that time more efficiently, while producing better work.

FIG. 7 compresses the nine guidelines in this Section into a writing checklist to use for any document.

WRITING IN GROUPS

Group writing is common in today's organizations, which emphasize team work at all levels and in all activities. For example, a successful proposal or technical manual may result from the combined effort of technical specialists, marketing experts, graphic artists, writers, editors, and word processors.

At its best, group writing benefits from the collective experience and specialties of all participants. This section describes five pointers for keeping a collaborative writing project on track:

1. Get to know your group

2. Set clear goals and ground rules

3. Use brainstorming techniques

4. Agree on a revision process

5. Use computers to communicate

• GUIDELINE 1: GET TO KNOW YOUR GROUP

If you're used to being a “lone ranger”—that is, a solitary writer—you have some adjustments to make in reaching consensus during a group project. The best way to open the channels of communication is to learn as much as possible about your colleagues. Here are two techniques for doing so:

• Spend time talking to group members before the project begins, establishing a personal relationship, or

• Use the first session for informal chatting, before you get down to business.

The point is this: The success of your group project may depend as much on having a good working relationship as it does on the technical specialties each member brings to the table.

= = = =

Directions: The following checklist addresses the nine guidelines in this Section. The only change here is that the guidelines are written as questions, for you to consider as you are writing.

PLANNING

Have you written a brief purpose statement?

2. Have you considered the obstacles your readers face?

3. Do you know the technical levels of your readers?

4. Do you know the decision-making levels of your readers?

5. Do you know exactly what decision-makers want?

6. Have you collected and documented information carefully?

7. Have you written an outline?

DRAFTING

8. Have you written the first draft quickly?

REVISING

9. Have you revised in stages?

FIG. 7 Writing checklist

= = = =

• GUIDELINE 2: SET CLEAR GOALS AND GROUND RULES

All groups should set goals and establish operating rules. Specifically, the following questions must be answered either before or during the first meeting:

• What is the main objective?

• How will tasks be distributed?

• How will conflicts be resolved?

• What's the schedule for the work?

• GUIDELINE 3: USE BRAINSTORMING TECHNIQUES

The most common error in group work is getting too critical too quickly. Just as an individual writer needs the chance to spill ideas onto paper during the outline stage, members of a group also need a chance to share ideas openly without concern for criticism. That opportunity for a non-judgmental pooling of ideas—or “brainstorming”—comes at the beginning of the group's work. Here's one strategy for brainstorming:

1. Ask the group recorder to take down ideas as quickly as possible

2. Write ideas on large pieces of paper affixed to the walls in a room

3. Use ideas written on the wall sheets to suggest additional ideas

4. Distribute results of the exercise to group members after the meeting

5. Meet again to choose ideas of most use in the project

• GUIDELINE 4: AGREE ON A REVISION PROCESS

Group drafting and editing can be difficult. Some people used to writing in solitude find it hard to reach consensus on matters of style. Follow these suggestions for keeping the collaborative process on track:

1. Avoid making changes for the sake of one individual's preference

2. Search for areas of agreement among members, not areas of disagreement

3. Make only those style and grammar changes that can be supported by rules of style, grammar, and word use (see Section B)

4. Ask the group's all-around best stylist to complete a final edit

Your goal should be a document that sounds as much as possible as if it were written by one person.

• GUIDELINE 5: USE COMPUTERS TO COMMUNICATE

Whether group members are in the same building or spread out across the world, they can benefit from using computers to communicate about the project. This technology, though changing as I write this guide, falls into two general categories:

• Asynchronous: Such software permits members to post messages to each other and to alter a document, though not at the same time that other group members are making contributions.

• Synchronous: Software of this type allows group members to carry on simultaneous computer “conversations” about a document in real time. With several windows on their screens, they can place messages on the screen at the same time they edit a document that appears on the screen of all participants involved in the computer conversation.

Computer conversations can go well beyond email. Perhaps the greatest advantage they lend to group work is the openness encouraged by such on line discussions. When coordinated with face-to-face sessions, such computer meetings produce results.

Next: Part 2: Structure: Achieving Speed and Quality (coming soon!)


Links:

Purdue Univ. Tech. Writing Guide

MIT Tech. Writing Guide

Wikiversity - Tech. Writing Guide