ENGL210: Technical Writing

5a. Utilize audience analysis to determine the proper accounting of a process

• How does audience analysis influence how you develop a process document?

Early in the process of writing a process document, you need to define the audience and their situation as it relates to the instructions you are writing. Typically, this means you must consider their level of familiarity with the topic, background, interests, demographics, and even cultural characteristics.

First, you should identify your primary audience:

• Experts know the theory and the product inside and out. They designed it, tested it, and know everything about it. They often have advanced degrees and operate in academic settings, or in research and development areas of the government and technology worlds. 
• Technicians build, operate, maintain, and repair the stuff experts design and theorize about. Their knowledge is also highly technical, but of a more practical nature.
• Executives make business, economic, administrative, legal, governmental, political decisions about the stuff experts and technicians work with. Executives are likely to have as little technical knowledge about the subject as nonspecialists.
• Nonspecialists have the least technical knowledge of all. Their interest may be as practical as technicians' but in a different way. They want to use the new product to accomplish their tasks; they want to understand the new power technology enough to know whether to vote for or against it in the upcoming bond election. Or, they may just be curious about a specific technical matter and want to learn about it – but for no specific, practical reason.

Then, you should analyze these other characteristics:

Background in knowledge, experience, and training in the subject. If you expect some of your readers lack a certain background, you should supply it in your document. But if they are experts, then there's probably no need to add background information.

Needs and interests. Think about what your audience expects from your process document, such as how they will use it. Also, consider what they do not want to read. Keep your document focused on what you think your audience is most interested in and what they need most.

Demographics: age, residence, area of residence, gender, political preferences. These factors do not usually play a big role for technical documents, but they could affect the language your use on the sentence level. Your narrative should be relevant.

Cultural differences. If you are writing for an international audience, be aware that formats for indicating time and dates, monetary amounts, and numerical amounts vary across the globe. Also, be aware that humor and figurative language (as in "hit a home run") may not be understood outside of your own culture.

Review Audience Analysis.

 

5b. Format and organize communications to document a process

• Define a heading, bulleted or numbered list, notice, figure, and table.
• Define parallel phrasing.
• What are some general principles of page design for a process document?
• Define a process document.
• Describe the elements in a process document: title, introduction, equipment and supplies, and steps.
• Define five types of steps in a process document: fixed-order, variable-order, alternate, nested, and stepless instructions.
• Name a type of process document that would be most suitable for using each of these types of instructions.

Page design refers to the type of typography and formatting professionally-designed documents use. Here are some guidelines for items in a process document:

Headings

• Headings should briefly describe the sections they introduce.
• Give headings a size and font that corresponds to their level of importance in your document.
• Use parallel phrasing (the same style of text, font, or size for similar items).
• Avoid lone headings and two consecutive headings without intervening text (stacked headings).

Lists

• Create a bulleted or numbered list to emphasize points, provide white space, and allow the reader to scan your text quickly.
• Introduce your list with a sentence or more of explanatory text (below the heading).
• Use a numbered list to put items in order; bulleted list if the order is not necessary.
• Use parallel phrasing (the same style of text, font, or size for similar items).
• Be consistent: capitalize or use lowercase for the first word of each item listed.
• Only punctuate list items with a period if they are complete sentences or are embedded dependent clauses.

Notices

• Notices are sections of text that alert or warn readers about a special point, exception, problem, or danger. They often appear in a box.
• Use a standard hierarchy of notices to make them more noticeable and appear more prominently.
• Avoid putting large amounts of text in bold, italics, or all caps.
• Explain when readers should heed the warning, what will happen if they ignore it, and how they can do to recover.
• For a numbered list, align notices to the text of the list item they apply to.

Figures

• Figures include visuals, such as charts, drawings, illustrations, photos, and schematics.
• Mention or cross-reference the figure in the text that precedes it.
• When necessary, place figure captions or titles below the figure.

Tables

• Create a table to clarify repeating pairs, triplets, or quadruplets of items.
• Mention or cross-reference the table in the text that precedes it.
• Include a table title above the table (or make it the top row), unless the content is obvious and includes few items.
• Include a heading for columns and rows.
• Left-align columns and headings that are text (unless they are one character).
• Right-align or decimal-align numerical data.
• Include the type of unit measurement used in the column or row headings (inches, millimeters, liters).
• Only use one or two fonts, and use color minimally.

The title of your process document should offer a task-oriented statement about what the document is about, such as "How to Change a Tire".

Your introduction should present the tasks or procedures the document will explain or cover (and perhaps not cover). Include background on what the audience needs to know to understand the instructions, indicate the conditions when these instructions should (or should not) be used, and alert readers to any general warnings, cautions, or dangers before proceeding. You can provide some technical background (details or theory), if you need to explain why your approach to this process is warranted or effective.

Equipment and Supplies

• Your equipment and supplies section should provide a list of items readers need to gather before starting the procedure, such as tools and supplies.
• Use a two-column list to add specifications to items, such as brand names, sizes, amounts, types, model numbers.

Steps

• The steps of your process document provides readers with a chronological list of the steps they need to follow to accomplish a task.
• Fixed-order steps must be performed in the order presented. For example, to change the oil in a car, you must drain the oil before you replace it with the new oil. Use a numbered list (usually, numbered in a vertical format).

• Variable-order steps can be performed in any order. For example, troubleshooting guides recommend areas you should check when you are trying to fix something. Use a bulleted list.
• Alternate steps present two or more ways to accomplish the same thing when various conditions could exist. Use a bulleted with "OR" inserted between alternatives.
• Nested steps break individual steps down into substeps. Indent the elements of your list further and sequence the substeps (such as with a., b., c., etc.).
• Stepless instructions cannot use a numbered vertical list because the situation may be too generalized or variable.

To review, see Common Page Design, Instructions, and Online Technical Writing Examples, Cases, and Models.

 

5c. Revise documents for greater clarity for the audience

• How do you revise a process document to ensure it reaches your audience most effectively?

Before you edit and proofread your process document, you may need to revise your content and organization to best reach your audience. Make sure you provide instructions that work, with explanations that help your reader build, operate, or repair something.

 

Information

Consider the amount of information you provide to your audience. Is it relevant to them?

Your readers need to understand your document. Have you neglected to include critical steps in your instructions, background material, or definitions of key terms? Can you omit unnecessary information that might confuse and frustrate your readers? Have you pitched information to the wrong kind of audience, such as to a group of experts, rather than technicians or novices. 

How many examples do you use to explain your steps? Examples and analogies provide a powerful tool for connecting with your audience. You can put a technical concept into a language and context that they can understand and relate to. Remember that your examples should also resonate with the technical expertise of your audience.

 

Organization

You might change the organization of your information to make it less confusing. For example, you may have provided too much, or too little, much background information upfront so certain readers get lost. You may need to consolidate your background information into the main text, or include it within your list of instructions, the point where readers need it most. 

Some individuals read with more confidence when they understand the "big picture", or the overarching principles or context before they get into the details. A strong introduction will help you make your case for why the reader needs to read and understand the entire document.

 

Format

Can you change the format of your document to make your process steps more clear? Use appropriate headings, lists, graphics, typography, margins, line length and spacing, type size, and style. For example, non-specialist readers may need to see more graphics that are easier to read, shorter lines, and larger type sizes. Use graphics to illustrate key actions and objects. Use headings to indicate your main sections and subheadings.

To review, read Audience Analysis.

 

5d. Revise documents for sentence-level concerns

• How should you incorporate the you-centered (reader-centered) style of writing?
• List some ways you can revise your documents at the sentence level to make your writing more engaging, clear, and easy-to-read.
• What does it mean to be a gender-savvy writer?

Once you feel you have finished your writing, print a rough draft of your work. Read it over critically and note any omissions, rough transitions, or incomplete ideas. Insert corrections into your document.

Revising your sentence style and length can make a big difference. For example, when you write instructions, using the imperative voice and "you" phrasing is vastly more understandable than the passive voice or third-person phrasing.

Personalizing your writing style and making it more relaxed and informal can make it more accessible and understandable. Put people and action in your writing; passive, person-less writing is hard to read. Similarly, use active verbs as opposed to "be" verb phrasing. All of this makes your writing more direct and immediate, so readers do not have to dig for meaning.

Using a you-centered style gives your writing an audience-centered tone by emphasizing the reader's interests and perspectives. When you stress your reader's interest or benefit, they are more likely to understand the information and act on your request. It involves using the second-person "you" and "your" rather than "we", "our", "I", or "mine". You should use this tone to be informative and helpful.

Work on your sentence clarity and economy. A writing style that is too wordy can be difficult and frustrating to read. An average of 15 to 25 words per sentence is about right; sentences over 30 words are too long. When you revise your rough drafts, put them on a diet – go through a draft line by line trying to reduce the overall word, page or line count by 20 percent. Try it as an experiment and see how you do. Removing fussy, unnecessary, detail and inflated phrasing will improve your writing. 

You can revise your sentences by doing the following.

• Replace weak "be" verbs and nouns with action-oriented verbs.
• Reconfigure noun stacks. If your sentences stack more than two nouns in a row, try to unpack them into different phrases.
• Reduce redundant phrasing: rewrite wordy set phrases, eliminate obvious qualifiers, and get rid of scattershot phrasing (which compound two or more synonyms).
• Remove the phrases "there is" and "it is" from sentences.
• Convert passive-voice sentences into the active voice.
• Revise subject-verb mismatches: make sure you have a concrete, specific noun, subject, and verb in each sentence.
• Break up long sentences that can be difficult to follow.

Our social conventions are changing in favor of gender-neutral writing. Since you do not want to offend any members of your audience, during your editing and revision practices, you should try to eliminate language that may be construed as sexist or gender-specific.

Revise gender-sensitive language as it relates to:

• Pronouns: avoid using masculine nouns and revise to "they", "she or he", alternate gender pronouns, or eliminate them altogether.
• Gendered nouns: avoid using words that end in "-man", collective expressions such as "you guys", and titles such as Mr., Miss, or Mrs. 
• Proper noun use should be consistent in references to male and female subjects. For example, refer to female subjects by only their last names, just as you would for men subjects. When you are writing about several people who have the same last name, use the full name of the person every time. Refer to female subjects with their full titles, just as you would for men. 

To review, see You-Centered Business Style, Audience Analysis, Power-Revision Techniques, Composing, and Gender-Sensitive Language.

 

5e. Apply the process of proofreading to polish documents to professional standards

Finally, proofread your work to correct any errors in punctuation, grammar, and spelling.

Here are some proofreading tips:

• Do not rely on your computer's spell checker, which is helpful, but not foolproof. Many spell checkers are based on a limited dictionary, and it will not catch common misspellings that form another valid word (such as "there" instead of "their", or "to" instead of "too").
• Do not rely on your computer's grammar checker. Many rely on a limited number of grammar rules and fail to explain why it deemed your sentence incorrect. Your sentence could be perfectly valid. Use a grammar checker to identify potential run-on sentences, incorrect verb tenses, or frequent use of the passive voice.
• Proofread for one type of error at a time, so you do not lose focus when trying to identify and revise too many things at once. For example, it is easier to catch grammar errors, when you are not checking for punctuation and spelling at the same time.
• Slowly read every word. Try reading your text out loud, since this allows you to hear how your words sound together. It will also force you to read what is on the page – it is easy to overlook what you had thought about writing, but did not get down.
• Separate your page into individual sentences, so you do not miss mistakes hiding in paragraphs or blocks of text.
• Circle every punctuation mark and ask yourself whether each one is correct.
• Read the sentences in your paper backwards, so you focus on your punctuation and grammar, rather than the content.

To review, see Power-Revision Techniques.

 

Unit 5 Vocabulary

• Alternate steps
• Executive, audience
• Expert, audience
• Figures
• Fixed-order steps
• Gender-sensitive language
• Headings
• Lists
• Nested steps
• Nonspecialists, audience
• Stepless instructions
• Tables
• Technician, audience
• Variable-order steps
• You-centered style