To ask intelligent questions, you first must read available documents and identify where information is missing or incorrect. The checklist in this section can guide you. The subsections after the checklist provide details about the different kinds of documents you might read to research your topic, as well as tips on how to read them.
CHECKLIST 7–1. IDENTIFYING MISSING INFORMATION
Use the following questions to make sure your information is com-plete and accurate:
• Do procedures seem complete or are there steps missing?
• Does the sequence of steps seem logical?
• Is the information specific? “Developers occasionally write is recom-mended or is suggested when they mean is required,” says Daniel Nolan in an article in Technical Communication, “and they write should or may when they mean must. . . . When you see is recom-mended, is suggested, should or may, . . . you should probably ask questions.”1
• What is the active agent? Often technical documents are written in passive voice, so the cause of action is unclear. For example, “a secondary station response must be initiated.” Who or what is doing the initiating?
• Is the information current? Question numerical values to be cer-tain they haven’t changed since the spec or previous manual was written. Check version numbers, dimensions, ranges, limits, and default values.
• Are all technical terms defined? List all terms, along with their def-initions, and question the ones you can’t define.
• Are all acronyms spelled out? List all acronyms and question the ones you don’t understand.
KEEPING TRACK OF QUESTIONS
Keep track of your questions in one or more of the following ways:
• Write them in a notebook that you reserve for information about the product.
• Write them on your copy of the spec or previous manual or on a hard copy of an online document.
• Write them on sticky notes that you can use to flag the pages in question.
I like the sticky notes, because I move them to the middle of the page when a question is answered, or I stick them to my computer display screen when I have trouble finding an answer.
READING PRODUCT SPECIFICATIONS
The first step in researching a product is to read all available product specs. Specs differ between product types and between companies. For example, if you’re writing a product monograph for a drug company, you won’t find anything called a spec, but other documents serve the same function.
Says one pharmaceutical writer, “The first thing you usually do is a library search through Medline. Medline is a database. You design a lit-erature search to pull out everything having to do with the drug. You look through your company’s literature, the final reports on clinical trials, on toxicologic trials, and so forth.”
If you write about computer software, you’ll encounter
• Functional specifications
• Internal reference specifications
• External reference specifications
• User interface change notices
• Software change notices
and a host of other technical-sounding documents. You’ll probably refer to them by acronyms—the ERS or the UICN—but for the purpose of this discussion, they’re all “specs.”
Specs have two uses to you as a writer: They are (1) a source of infor-mation about the product, and (2) a source of questions for the product developer (who may also be the author of the spec).
Some specs are extremely well written and clear, but many are not.
Spec writers usually don’t define jargon or acronyms. They tend to use terminology inconsistently, calling something an “index unit” in one place and an “index object” in another. Therefore, some skill in reading specs will help you extract the information you need, with-out succumbing to confusion or boredom. The following tips should help.
TIPS ON READING A SPEC
1. Make a photocopy of the spec so you can mark it up.
2. Write your purpose at the top of the spec. What kind of infor-mation do you need from the spec? For example, “Installing the software.”
3. Skim the whole spec and highlight everything you might need—
draw a line along the side of relevant sections.
4. Go back and read the sections you’ve highlighted. As you read, do the following:
• Mark or circle paragraphs that you can use verbatim in the first draft of your manual. (Plagiarism in tech writing is totally legit, as long as you “lift” material from within your company.)
• List terms and acronyms, as recommended earlier in this chapter.
• List questions that seem relevant to your purpose. For example, if the spec says, “The default of 300 applies for most configu-rations,” you might ask, “Under what circumstances would the user need to use a different value?”
READING PREVIOUS DOCUMENTS
In addition to specs, other written materials can be sources of informa-tion and quesinforma-tions. Most commonly, you’ll be able to read previous doc-umentation written by technical writers about earlier versions of the product. These documents can be both on paper and online. They are valuable not only for technical information but also as examples of the manual formats, online organization and screen layouts, and the “house style” used by your company.
Reading previous documentation is similar to reading specs, only eas-ier. The following tips will help you read a manual for information and questions.
TIPS ON READING PREVIOUS DOCUMENTATION
1. Whether the document is a paper manual or online, get a paper copy you can write on. Now you can mark it up as you did the product specification.
2. Highlight useful information.
3. Cross out information that you know is outdated.
4. In a notebook, list terms and acronyms next to their definitions, as described earlier. The acronyms and terms in previous documenta-tion should already be defined.
5. List questions that you think need to be clarified before you can begin writing.
6. Talk to the previous document’s author, if available, to find out what problems and questions came up while documenting the last version of the product.
7. If you think you can use a lot of the previous document, ask for the most current online version or “source file”—one that you can manipulate on your computer. Later, you can build your new doc-ument using large chunks of existing material.
Sometimes no spec, previous documentation, or written material is available about a product. If the product is a groundbreaking,
one-of-a-kind new gizmo, you may have to go straight to its designer for informa-tion. However, most products are like something else that already exists, perhaps from a different company. To increase your knowledge of your subject, read manuals about competing products, which you can some-times get from your marketing or engineering department. At least you’ll understand some of the concepts that went into your product. This knowledge will help you when you talk to your product’s developer.