Guide to Tech Writing -- Five Quick Technical Writing Tips



Home


Successful writing on the job is not the product of inspiration, nor is it merely the spoken word converted to print; it’s the result of knowing how to structure information using both text and design to achieve an intended purpose for a clearly defined audience. The best way to ensure that your writing will succeed (whether it’s in the form of a memo, a résumé, a proposal, or a Web page) is to approach writing using the following steps:

  • 1. Preparation


  • 2. Research


  • 3. Organization


  • 4. Writing


  • 5. Revision

At first, you’ll most likely need to follow these steps consciously -- even self-consciously. The same is true the first time you use new software, interview a candidate for a job, or chair a committee meeting.

With practice, the steps become nearly automatic. That isn’t to suggest that writing becomes easy. It doesn’t. However, the easiest and most efficient way to write effectively is to do it systematically.

As one masters these steps, keep in mind that they are interrelated and often overlap. For example, your readers' needs and your purpose, which you determine in step 1, will affect decisions you make in subsequent steps. You may also need to retrace steps. When you conduct re search, For example, you may realize that you need to revise your initial understanding of the document's purpose and audience. Similarly, when you begin to organize, you may discover the need to return to the re search step to gather more information.

The time required for each step varies with different writing tasks.

When writing an informal memo, for example, you might follow the first three steps (preparation, research, and organization) by simply listing the points in the order you want to cover them. In such situations, you gather and organize information in your mind as you consider your purpose and audience. For a formal report, the first three steps require well-organized research, careful note-taking, and detailed outlining. For a routine e-mail message to a coworker, the first four steps merge as you type the information onto the screen. In short, the steps expand, contract, and at times must be repeated to fit the complexity or context of the writing task.

Dividing the writing process into steps is especially useful for collaborative writing, in which you typically divide work among team members, keep track of a project, and save time by not duplicating effort. For details on collaborating with others and using electronic tools to help you manage the process, see collaborative writing.

* Preparation Writing, like most professional tasks, requires solid preparation. In fact, adequate preparation is as important as writing a draft. In preparation for writing, your goal is to accomplish the following four major tasks:

  1. • Establish your primary purpose.


  2. • Assess your audience (or readers) and the context.


  3. • Determine the scope of your coverage.


  4. • Select the appropriate medium.

Establishing Your Purpose. To establish your primary purpose simply ask yourself what you want your readers to know, to believe, or to be able to do after they have finished reading what you have written. Be precise. Often a writer states a purpose so broadly that it’s almost use less. A purpose such as "to report on possible locations for a new re search facility" is too general. However, "to compare the relative advantages of London, Berlin, Singapore, and San Francisco as possible locations for a new research facility so that top management can choose the best location" is a purpose statement that can guide you throughout the writing process. In addition to your primary purpose, consider possible secondary purposes for your document. So, a secondary purpose of the research-facilities report might be to make corporate executive readers aware of the staffing needs of the new facility so that they can ensure its smooth operation regardless of the location selected.

Assessing Your Audience and Context. The next task is to assess your audience. Again, be precise and ask key questions. Who exactly is your reader? Do you have multiple readers? Who needs to see or to use the document? What are your readers' needs in relation to your subject? What are their attitudes about the subject? (Skeptical? Supportive? Anxious? Bored?) What do your readers already know about the subject? Should you define basic terminology, or will such definitions merely bore, or even impede, your readers? Are you communicating with international readers and therefore dealing with issues inherent in global communication?

===============

ESL TIPS for Considering Audiences

In the United States, conciseness, coherence, and clarity characterize good writing. Make sure readers can follow your writing, and say only what is necessary to communicate your message. But, no writing style is inherently better than another, so to be a successful writer in any language, you must understand the cultural values that underlie the language in which you are writing. See also awkwardness, copyright, global communication, English as a 2nd language, and plagiarism.

Throughout this guide we have included ESL Tips boxes like this one with information that may be particularly helpful to nonnative speakers of English. See the Contents by Topic on the inside front cover for listings of ESL Tips and ESL Trouble Spots, entries that may be of particular help to ESL writers.

==========

For the research-facilities report, the readers are described as "top management." Who is included in that category? Will one of the people evaluating the report be the Human Resources Manager? If so, that person likely would be interested in the availability of qualified professionals as well as in the presence of training, housing, and perhaps even recreational facilities available to potential employees in each city. The Purchasing Manager would be concerned about available sources for materials needed by the facility. The Marketing Manager would give priority to the facility's proximity to the primary markets for its products and services and the transportation options that are available. The Chief Financial Officer (CFO) would want to know about land and building costs and about each country's tax structure. The Chief Executive Officer (CEO) would be interested in all this information and perhaps more. As with this example, many workplace documents have audiences com posed of multiple readers. You can accommodate their needs through one of a number of approaches described in the entry audience.

In addition to knowing the needs and interests of your readers, learn as much as you can about the context. Simply put, context is the environment or circumstances in which writers produce documents and within which readers interpret their meanings. Everything is written in a context, as illustrated in many entries and examples throughout this guide. To determine the effect of context on the research-facilities re port, you might ask both specific and general questions about the situation and about your readers' backgrounds: Is this the company's first new facility, or has the company chosen locations for new facilities be fore? Have the readers visited all three cities? Have they already seen other reports on the three cities? What is the corporate culture in which your readers work, and what are its key values? What specific factors, such as competition, finance, and regulation, are recognized as important within the organization?

Determining Scope. Determining your purpose and assessing your readers and context will help you decide what to include and what not to include in your writing. Those decisions establish the scope of your writing project. If you don’t clearly define the scope, you will spend needless hours on research because you won’t be sure what kind of information you need or even how much. Given the purpose and audience established for the report on facility locations, the scope would include such information as land and building costs, available labor force, cultural issues, transportation options, and proximity to suppliers.

However, it probably would not include the early history of the cities being considered or their climate and geological features, unless those aspects were directly related to your particular business.

Selecting a Medium. Finally, you need to determine the most appropriate medium for communicating your message. Professionals on the job face a wide array of options-from e-mail, fax, voice mail, video conferencing, and Web sites to more traditional means like letters, memos, reports, telephone calls, and face-to-face meetings.

The most important considerations in selecting the appropriate medium are the audience and the purpose of the communication. For example, if you need to collaborate with someone to solve a problem or if you need to establish rapport with someone, written exchanges could be far less efficient than a phone call or a face-to-face meeting. How ever, if you need precise wording or you need to provide a record of a complex message, communicate in writing. If you need to make in formation that is frequently revised accessible to employees at a large company, the best choice might be to place the information on the company's intranet site. If reviewers need to submit their written comments about a proposal, you can either send them paper copies of the proposal that can be faxed or scanned, or you can send them the word processing ?le to insert their comments electronically. The comparative advantages and primary characteristics of the most typical means of communication are discussed in selecting the medium.

Research

The only way to be sure that you can write about a complex subject is to thoroughly understand it. To do that, you must conduct adequate re search, whether that means conducting an extensive investigation for a major proposal-through interviewing, library and Internet research, and careful note-taking-or simply checking a company Web site and jotting down points before you send an e-mail to a colleague.

Methods of Research. Researchers frequently distinguish between primary and secondary research, depending on the types of sources consulted and the method of gathering information. Primary research refers to the gathering of raw data compiled from interviews, direct observation, surveys, experiments, questionnaires, and audio and video recordings, for example. In fact, direct observation and hands-on experience are the only ways to obtain certain kinds of information, such as the behavior of people and animals, certain natural phenomena, mechanical processes, and the operation of systems and equipment. Secondary research refers to gathering information that has been analyzed, assessed, evaluated, compiled, or otherwise organized into accessible form. Such forms or sources include guides, articles, reports, Web documents, e-mail discussions, and brochures. Use the methods most appropriate to your needs, recognizing that some projects will require several types of research and that collaborative projects may require those re search tasks to be distributed among team members.

Sources of Information. As you conduct research, numerous sources of information are available to you, including the following:

• Your own knowledge and that of your colleagues.

• The knowledge of people outside your workplace, gathered through interviewing for information.

• Internet sources, including Web sites, directories, archives, and discussion groups.

• Library resources, including databases and indexes of articles as well as guides and reference works.

• Printed and electronic sources in the workplace, such as various correspondence, reports, and Web intranet documents.

Consider all sources of information when you begin your research and use those that are appropriate and useful. The amount of research you will need to do depends on the scope of your project. See also documenting sources.

Organization

Without organization, the material gathered during your research will be incoherent to your readers. To organize information effectively, you need to determine the best way to structure your ideas; that is, you must choose a primary method of development.

Methods of Development. An appropriate method of development is the writer's tool for keeping information under control and the readers' means of following the writer's presentation. As you analyze the information you have gathered, choose the method that best suits your subject, your readers' needs, and your purpose. For example, if you were writing instructions for assembling office equipment, you would naturally present the steps of the process in the order readers should perform them: the sequential method of development. If you were writing about the history of an organization, your account would most naturally go from the beginning to the present: the chronological method of development. If your subject naturally lends itself to a certain method of development, use it-do not attempt to impose another method on it.

Often you will need to combine methods of development. So, a persuasive brochure for a charitable organization might combine a specific-to-general method of development with a cause-and effect method of development. That is, you could begin with persuasive case histories of individual people in need and then move to general in formation about the positive effects of donations on recipients.

Outlining. Once you have chosen a method of development, you are ready to prepare an outline. Outlining breaks large or complex subjects into manageable parts. It also enables you to emphasize key points by placing them in the positions of greatest importance. By structuring your thinking at an early stage, a well-developed outline ensures that your document will be complete and logically organized, allowing you to focus exclusively on writing when you begin the rough draft. An out line can be especially helpful for maintaining a collaborative-writing team's focus throughout a large project. However, even a short letter or memo needs the logic and structure that an outline provides, whether the outline exists in your mind or on-screen or on paper.

At this point, one must begin to consider layout and design elements that will be helpful to your readers and appropriate to your subject and purpose. So, if visuals such as photographs or tables will be useful, this is a good time to think about where they may be positioned to be most effective and if they need to be prepared by some one else while you are writing and revising the draft. The outline can also suggest where headings, lists, and other special design features may be useful.

Writing

When you have established your purpose, your readers' needs, and your scope and have completed your research and your outline, one will be well prepared to write a first draft. Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or punctuation. Writing and revising are different activities; refinements come with revision.

Write the rough draft, concentrating entirely on converting your outline into sentences and paragraphs. You might try writing as though you were explaining your subject to a reader sitting across from you.

Don’t worry about a good opening. Just start. Don’t be concerned in the rough draft about exact word choice unless it comes quickly and easily-concentrate instead on ideas.

Even with good preparation, writing the draft remains a chore for many writers. The most effective way to get started and keep going is to use your outline as a map for your first draft. Don’t wait for inspiration-- one needs to treat writing a draft as one would any on-the-job task. The entry writing a draft describes tactics used by experienced writers-discover which ones are best suited to you and your task.

Consider writing an introduction last because then one will know more precisely what is in the body of the draft. Your opening should announce the subject and give readers essential background information, such as the document's primary purpose. For longer documents, an introduction should serve as a frame into which readers can’t the detailed information that follows.

Finally, one will need to write a conclusion that ties the main ideas together and emphatically makes a final significant point. The final point may be to recommend a course of action, make a prediction or a judgment, or merely summarize your main points-the way you conclude depends on the purpose of your writing and your readers' needs.

Revision

The clearer finished writing seems to the reader, the more effort the writer has likely put into its revision. If you have followed the steps of the writing process to this point, one will have a rough draft that needs to be revised. Revising, however, requires a different frame of mind than does writing the draft. During revision, be eager to find and correct faults and be honest. Be hard on yourself for the benefit of your readers. Read and evaluate the draft as if one were a reader seeing it for the first time.

Check your draft for accuracy, completeness, and effectiveness in achieving your purpose and meeting your readers' needs and expectations. Trim extraneous information: Your writing should give readers exactly what they need, but it should not burden them with unnecessary information or sidetrack them into loosely related subjects.

Don’t try to revise for everything at once. Read your rough draft several times, each time looking for and correcting a different set of problems or errors. Concentrate first on larger issues, such as unity and coherence; save mechanical corrections, like spelling and punctuation, for later proofreading. See also ethics in writing.

Finally, for important documents, consider having others review your writing and make suggestions for improvement. For collaborative writing, of course, team members must review each other's work on segments of the document as well as the final master draft. Use the List of the Writing Process to guide you not only as you revise but also throughout the writing process.

Style Guides and Standards---Organizations and professional associations often follow such guides as The Chicago Manual of Style, MLA Style Manual and Guide to Scholarly Publishing, and United States Government Printing Office Style Manual to ensure consistency in their publications on issues of usage, format, and documentation. Because advice in such guides often varies, some organizations set their own standards for documents. Where such standards or specific style guides are recommended or required by regulations or policies, you should follow those style guidelines.

PREV:
NEXT:

top of page   Home