Pantex Technical Writing Workshop: 3

3. Progress Report: Tech Writing Today.

Technical Writing Goals

There are many types of technical documents. Nonetheless, they all strive to meet these goals:

Clarity: The first and most crucial concern is intelligibility. Does your target audience understand the topic? Will the document solve her problem? Something like "the customer is always right," "the reader must understand or the writing fails."

A recent text suggests that the average phone call to a customer-support service costs the business $20 to answer. Phone support services largely exist because manuals are too daunting or intimidating or unappealing to read. The second concern is safety. Many technical procedures are dangerous to both those performing the operation and to others affected by the procedure -- or, in this case, possibly "impacted" by the procedure.

Honesty: There is a necessary degree of persuasion in all technical writing. You want readers to trust the authority of the writer. You want readers to have a professional concern for the topic.

Tech writing is not advertising. Its major purpose is to explain, not sell. Internal documents are usually forthright and unconcerned about the dignity or public image of the company.
"External" documents, addressed to those outside the organization, are often revised with a concern for image, customer loyalty, stock price, and similar sales or reputation concerns. We are familiar with the dangers of allowing these to drift into different directions as they did with the tobacco industry, Firestone Tires, top-heavy SUVs, etc.

Accuracy: Proofread to catch typos, omissions, and other errors. Use spell checkers and grammar checkers. Three or four minutes of proofreading e-mail and memos is time well spent. Ask the guys who sent up the first Hubble telescope mirror that was useless because a "+" (plus) numerical figure should have been a "-" (minus). A similar mistake recently doomed the science mission sent to Mars. Typos and data entry errors may seem trivial, but they infect reader confidence concerning the entire document.

Comprehensiveness: Because you write about processes, mechanisms, and theories that you know well, it is easy to skip a step, a detail, or a caution. In its "Guidelines for Submissions," a biology journal sets this standard for thoroughness:

A scientific article reporting on an experiment that compares the
reaction of a new strain of bacterium to two different compounds
will not be considered for publication unless the writer has fully
described the methods used in the experiment. Because other
scientists should be able to replicate the researcher's methods,
every detail must be provided, including the names of the
companies from which the researcher obtained all the materials.

Accessibility: Partition documents with an outline system, headlines, and a table of contents. The informative abstract is likely to be the only component of a document that nearly every reader reads. Websites of more than a few pages should have a site map listing every page in the site.

Conciseness: Be thorough, but concise. These goals pull in opposite directions. The way to meet both goals is by partitioning the document with an outline, headlines, a table of contents, and perhaps an index.

Long documents become "short" because readers can find those sections that they are interested in.
Strangely, repetition can contribute to conciseness. It is usually better to duplicate a section under a heading rather than to tell the reader to flip through the document to find the section somewhere else. Controlled repetition creates emphasis and helps identify major themes or ideas.
Some writers are like gardeners who are vigilant to spot weeds. They hunt wordy constructions, clichés, and arcane jargon. Good for them. Occasionally this can detract from accuracy and comprehensiveness.

You must juggle all three concerns. The overriding goal is clarity and effective communication.

Professional Appearance: We all do it. You form an impression of a document from a global glance. You decide whether or not to wait for a Web page to fully load depending on how the first elements look. When writing documents, our first instinct is to claim that our ideas are all important and how they are conveyed doesn't matter very much. The appearance of your documents always says something about your attention to detail and how well you are performing your job.

Grammar: Almost everyone hates grammar, especially when they make a mistake. The exceptions are the pedants who use it to harangue the rest of us. Of course there are grammatical standards that should not be violated, because doing so reduces clarity and trust. If you demonstrate that either you do not know simple grammar, or cannot be bothered to proofread your document to catch such errors, why should I trust that you know what you are writing about?

Visual Organization & Layout

Reader oriented documents allow readers to quickly find what they need to know. In the first version of the document below readers are forced to read through the entire document to find what they are looking for or even to discover if the document contains information relevant to them. Notice how the first version is author centered by being too conversational. Typically we read such documents with a yellow marker in hand to create the kind of headline organization illustrated in the second version below.

To: David Stewart
From: Kathy Hillman
Date: 22 Aug. 01
Subject: Short Course Request from Ocean Drilling

      Because I will be away on a three-week teaching assignment, I would appreciate you handling the following request, which came in just as I was preparing to leave today.
      Randy Allen, director of the offshore drilling research team, would like a short-course in writing offshore safety inspection reports. He would like the short-course taught from 2--4pm Monday--Friday afternoons, beginning week after next. The class must be scheduled then, as the team leaves the following week for their next research cruise.
      The drilling research team spends two weeks each month on cruise. After they return, they have one week to complete their reports before briefing begins for the next research expedition. Because of their rigid schedule, they cannot attend our regularly scheduled writing classes.
      Allen says that the cultural and educational backgrounds of the team are varied. Five of the ten regular researchers are native Europeans who attended only European universities. Of the remaining five, two have American degrees, and three attended school in Canadian universities. As a result of their varied educational backgrounds their reports lack uniform handling of English and organization. All the researchers have expressed interest in having a short review of standard English usage so that their reports to management will be more uniform.
      Sarah Kelly says she can develop a class for the Drilling team. We have materials on reports, style, and standard usage in the files. She can work with Ocean Drilling to determine the best report structure and develop a plan. These items can be easily collected and placed in binders. We also have summary sheets on each topic that will be good reference aids when the researchers write their reports following their cruise.
      Sarah will contact you Monday morning. If her teaching the class meets with your approval, please give Randy Allen a call, at extension 721, before noon. He has a staff meeting scheduled at 1:30 and would like to announce the short course then. If fact, if the course cannot be scheduled this month, it cannot be taught for seven months because of off-season cruise schedules. Allen wants this course before the team begins a series of four reports during the off-season.
      Please arrange a time for Sarah to meet with Allen so they can go over several previous reports. Sarah wants to be sure that what she covers in the course is what they need.
      If you need to talk to me about this request, I will be staying at the Hyatt in New Orleans.

Version 1: No Visual Organization

To:          David Stewart
From:     Kathy Hillman
Date:      22 Aug. 01
Subject: Request from Offshore Drilling Team for a Writing Course

ACTION: Decide to authorize a special course on writing for
Offshore Drilling by Monday, Aug. 24, at noon.

Because I will be away on a three-week teaching assignment, please respond to the following request, which came in just as I was preparing to leave today. If you wish to talk to me about this request, I will be staying at the Hyatt in New Orleans.

Offshore Drilling Wants a Short Course on Writing
Randy Allen, director of the offshore drilling research team, requested a short-course in writing offshore safety inspection reports. He would like the short-course taught from 2 to 4 pm, Monday through Friday afternoons, beginning the week after next. Allen wants this course taught before the offshore drilling team begins to write a series of four reports during the off-season.

They Cannot Attend Our Regular Writing Classes
The class must be scheduled at the time Randy requested because the team leaves the following week for their next research cruise. The team spends two weeks each month on cruise. After they return, they have one week to complete their reports before briefing begins for the next research expedition. Because of this rigid schedule, they cannot attend our regularly scheduled writing classes. If fact, if the course cannot be scheduled this month, it cannot be taught for seven months because of off-season cruise schedules.

The Offshore Drilling Team Needs Writing Help
Allen says that the cultural and educational backgrounds of the team are varied. Five of the ten regular researchers are native Europeans who attended only European universities. Of the remaining five, two have American degrees, and three attended school in Canadian universities. As a result of their varied educational backgrounds their reports lack uniform handling of English and organization. Allen reports that all the researchers have expressed interest in having a short review of standard English usage so that their reports to management will be more uniform.

Sarah Kelly Can Develop and Teach the Class
Sarah Kelly says she can develop a class for the drilling team. We have materials on reports, style, and standard usage in the files. She can work with Ocean Drilling to determine the best report structure and develop a plan. These items can be easily collected and placed in binders. We also have summary sheets on each topic that will provide good reference aids when the researchers write their reports following their cruise.

Please Decide This by Monday Noon (24 Aug. 01). Call Randy Allen: #721
Sarah will contact you Monday morning. If you approve of her teaching the class, please give Randy Allen a call, at extension 721, before noon. He has a staff meeting scheduled at 1:30 and would like to announce the short course then.

Please arrange a time for Sarah to meet with Allen so they can go over several previous reports. Sarah wants to be sure that what she covers in the course is what they need.

Version 2: Document Revised for Visual Organization

Back to navigation