Getting Your Arms around a Technical Document - dummies

Getting Your Arms around a Technical Document

By Sheryl Lindsell-Roberts

The purpose of writing a technical document is to explain or report on a technical or complex subject. Therefore, unless you’re the technical guru writing about something you know intimately, you must research the subject. Gathering data — learning all you can about the product or service — is the lifeblood of the project.

Internal research

If your research is internal, gather your information by interviewing SMEs (subject matter experts) and others involved in the project, observing people in and around the workplace, reading spec sheets and company literature, and just snooping around. Here are some tips for keeping your nose to the grindstone without getting it cut off:

  • Get to know the product or service intimately.

• Test it. Use it. Hug it. Learn all you can.

• Study system specs and engineering drawings.

• Interview the SME. Bring a list of questions you prepared.

  • Absorb the big picture.

• Find out about the purpose of the produce or service, who’ll use it, why, and when.

• Learn the acronyms.

• Become familiar with the good and bad features of the product or service.

• Learn about any possible flaws with the product, such as what features may break, malfunction, or cause problems.

  • Cozy up to the marketing and sales departments.

• Learn the advantages and disadvantages of the product or service.

• Understand the features and benefits you need to highlight.

• Know how the manual will be distributed and updated.

• Find out whether there are related publications or manuals.

  • Find out whether you need to prepare unpacking instructions or a parts lists.

• Ask what’s in the shipping carton.

• Ask whether the user needs instructions to install or assemble the item.

  • Gather as much written or graphical data as you can. You can always discard what you don’t need.

• Decide what photos or graphics you need.

• Get copies of a style manual or standard text that similar projects used.

It’s important that you don’t merely trust your memory. Take copious notes while doing your research.

External research

You do external research by interviewing people outside your organization, visiting the library, or surfing the Web. Here’s some advice to make your job easier:

  • Interview people outside your company. You can either visit people personally or send a questionnaire. Which to do, of course, depends on the nature of your research. If you need to gather information from a lot of people, you may find a questionnaire is appropriate. If you need to meet face to face with one or more people, follow these guidelines:

• Prepare a list of objectives and questions beforehand.

• Let the interviewee do most of the talking. After all, you’re there to learn.

• Grab all the literature the interviewee is willing to share.

• Take copious notes or use a tape recorder, if appropriate.

  • Do research at the library. There are a variety of ways to use the library for research. If you need help using any of the following library services, ask the librarian:

Card catalog: Card catalogs are alphabetically arranged by author, title, and subject to reflect all the books and resources the library owns.

Bibliographies and periodical indexes: Bibliographies list periodicals, books, and other published research in a wide variety of subject areas. Periodical indexes list magazines, journals, and newspaper articles. Libraries sometimes house bibliographies and periodicals in a separate room. Newer indexes may be on the shelf, while older indexes may be in another part of the library or in microform.

Reference works: These include encyclopedias, dictionaries, handbooks, manuals, statistical sources, atlases, and more.

  • Surf the Web. If you don’t know the URL of the site you want, access one of the popular search engines. Following are a few highlights:

Type in a keyword or phrase. The search engine looks for documents that have your keyword(s). It then ranks the sites based on how many times your keyword appears in the document, whether the keyword appears in the title, how early the keyword appears in the text, and so on.

Try to make your search as narrow as possible. Otherwise, you may get thousands of hits. For example, if you search for dog, you get Web sites for more dogs than you want barking at you. If you search for poodle, you get all types of poodles. If you search for toy poodle, you narrow the search to the toy variety only.