WRTG 393 - Week #1

Criteria for evaluating the usability of instructions include:

accuracy ease of understanding and following logical arrangement, with one action per step clear organization so that pieces of information can be found efficiently

"C.R.A.P."

acronym for the basic principles of readability. It originated with the influential designer and writer Robin Williams. C - Contrast R - repetition A - alignment P - proximity

Technical writing needs to . . .

address the needs of many different people. It is written to readers at all levels, from specialist to novice, and to people with widely different backgrounds.

a "you" attitude

address your readers in a personable tone and focus on what they want to gain from the document rather than on what you want to gain from them.

How to plan for instructions?

analyze the activity for which you are creating them, as well as your audience and purpose. Ask yourself: Who is performing the activity? What are they doing? When is it performed? Where is it performed? How is it done? Why is it being done?

headings

are important in creating a visually appealing document. A sans serif font (such as Arial) works well. Use headings to separate major sections and subsections of a document. You can use different heading levels. Just be sure to make the heading styles consistent in size and style.

a warning

attempts to protect readers from bodily harm For example . . . 1. On a flat surface, extend the jack until the car is approximately 6 to 8 inches off the ground. WARNING: Do not jack up the car up on a hill. The car can roll off the jack.

All lists need to . . .

be introduced with a lead-in or a header. If you were citing ways to improve customer service in an e-mail message to your coworkers, you would not start with a bulleted list of ideas. You would introduce the list with a clause. for example: To improve productivity, I propose that we # decrease overtime hours # drop our Acme account # hire an additional salesperson If you are writing an introductory clause that ends with a noun or a phrase such as "the following," place a colon at the end of that clause. If the clause ends on a preposition (such as "with" or "in"), do not use a colon. A good rule of thumb is to avoid using a colon if the introductory clause flows into any one of the bullet points so as to form a complete, uninterrupted sentence. No colon is needed for this type of list: His painting included # the sand # seagulls # the waves A colon is needed here: His painting included the following: # the sand # seagulls # the waves

As you develop instructions, you should test them for . . .

completeness, accuracy, and understandability. Testing instructions during their development can identify what is useful and beneficial as well as what needs improvement. Testing helps to ensure a high-quality product.

Tables are useful in . . .

condensing information and clearly denoting or specifying options. One type of table, an if/then or decision table, is an effective means for presenting options to readers in a clear, easy-to-follow format.

Positive terminology

Encourages readers to respond favorably to instructions. for example: instead of saying ""Do not wash the ground coffee container in an automatic dishwasher." You would say ""Always wash the ground coffee container by hand."

Imperative mood

Focuses readers on the action. Putting the action verb at the beginning of a command in the imperative mood emphasizes the action, reinforcing what the reader should do. for example: Pour the water on the soil covering the seeds until the soil is wet but not saturated. Using the imperative mood with active voice conveys directly and clearly to readers what actions they should take.

how to organize instructions

Instructions are generally organized chronologically, telling readers how to complete a task through a series of steps. In your introduction, provide an overview of the instructions and present information that relates to the entire activity. The introduction can include the purpose; the intended reader; any assumptions, definitions, necessary materials, and equipment; and an advance organizer. In the body of the instructions, present the detailed steps including the action, any results of the action, safety information, and other explanations or definitions If a conclusion is needed, you can wrap up the instructions by summarizing the major steps, referring readers to other information, or describing what to do if a problem occurs.

decision table

It is often difficult to determine how your audience may misinterpret your instructions. Longer sets of instructions may need troubleshooting sections. A decision table is the best way to organize troubleshooting guides and instructions where a user needs to make a decision, or has a choice.

serif and sans-serif fonts

Serif fonts have small strokes at the end of the letters Sans Serif fonts do not have the decorative part of the font. Sans serif fonts, like Helvetica or Futura, are simple and smooth; the letters don't display the "feet" and ornamentation (serifs) that serif fonts do. Sans serif fonts are often used for headlines, but serif fonts are more likely to be used for body text. Many typographers think serif fonts (also called Roman fonts) make large blocks of body text easier to read.

partitioning in technical descriptions

Similar to chunking, partitioning means breaking down an object into its components or a process into smaller, related steps or stages. Partitioning can help readers understand how the object is constructed and operates or what happens during each step of a process. for example: A screw consists of two parts: stem and head. The stem is circular and has threads embedded in its surface for driving it into another substance. The head is raised, has a greater diameter than the stem, is often circular, and is slotted so a tool can drive the stem into another surface. You insert a tool, such as a screwdriver, into the slot in the head to drive the stem into a substance, such as wood.

What makes for good technical writing?

Technical writing must be honest, accurate, accessible, concise, and professional in appearance.

Technical descriptions

explain how equipment, machines, or objects operate and are assembled and what happens during a process. A process can include an event, such as a hurricane, or an activity, such as the transmission of an e-mail message. Technical descriptions of these objects and processes help readers understand what they do, how they function, when and where they happen, and why. They can also help readers understand a topic, especially an abstract topic.

In the workplace, flawed writing can . . .

have serious consequences; it can cause lost time and revenue, it can lead to equipment failure, and—in the most extreme cases—it can have legal ramifications

Lists

help break up information for your readers. Scanning a list of items is much easier than reading the items horizontally, separated by commas. Employ lists for supplies, prices, steps, etc. If the reader should follow directions in a strict order, number those directions. If the reader has different options or if the directions are not absolutely required, bullet those items. All items in a list must be parallel. This means that each item needs to have the same grammatical structure. If you begin a series with a verb, use verbs throughout the series. Avoid mixing phrases and sentences.

Graphics are especially beneficial for . . .

instructions directed to an international audience. In fact, these instructions may be completely graphical. For instance, instructions designed to explain safety and evacuation procedures on airlines are often completely graphical.

In the workplace, solid writing can . . .

lead to promotions, increased profits, and improved customer relations.

technical writing

nonfiction writing targeted to a specific audience and created for a specific purpose, such as to inform or persuade.

Safety information includes . . .

notes, cautions, warnings, and danger alerts. The American National Standards Institute (ANSI) publishes Standard Z535.4, which identifies these four levels with signal words (Note, Caution, Warning, and Danger), a symbol, and color. safety information should be easy to read so readers can grasp it quickly. Display this information prominently and at the appropriate point in the instructions when readers need it, immediately before the action, not after it has occurred.

Graphics serve numerous purposes in instructions, including . . .

showing the parts, equipment, or materials needed for completing a task showing how a piece of equipment is assembled or how one piece relates to another directing people to different types of information identifying different types of information illustrating the results of an action

reader-oriented

something written from the readers' perspective. instructions are a reader-oriented form of technical writing Good instructions not only tell readers how to do something but also persuade and encourage them to try a new, unfamiliar task. Clear, precise, logical instructions result in satisfied, productive readers, whereas unclear, ambiguous instructions result in frustrated readers.

A technical document should contain . . .

straightforward wording that is short and easy to understand

Usability testing

the process of conducting experiments with people who use the instructions to see how easily and accurately they can complete the task and how well the instructions work. The goals of this testing include developing safe and accurate products and services, increasing customer satisfaction, and reducing customer-support costs.

white space

the space in margins and in between sections of text. Clear technical writing effectively uses white space. It also includes appropriate use of headings, graphics, lists, and alignment to help visually "chunk" information for readers.

The main purpose behind most technical writing is . . .

to convey information and ideas accurately and efficiently. Most technical documents are written to inform readers about a specific subject or to persuade readers to make a decision or come to a conclusion.

a note

used to clarify a point within a step of an instruction. This is the lowest level of precaution. For example . . . 1. Loosen the lug nut. NOTE: If the lug nut will not move, spray it with WD-40.

a caution

warns readers of mistakes they might make. Generally, a caution refers to possible equipment damage. for example . . . 1. Securely fasten the wrench to the lug nut and pull the handle down. CAUTION: If the wrench is not securely fastened to the lug nut and pressure is applied, you may strip the lug nut.

Effective technical writing meets 4 certain criteria

1. addresses specific readers 2. utilizes elements of design 3. has a specific purpose 4. is accurate, clear, concise, consistent, and complete

elements of contrast

1. size 2. font size / style /weight 3. direction (vertical, horizontal, circular, etc.) or position (top, bottom, side) 4. alignment (center, left, right, justified) 5. graphic elements (photos, banners/bands, pull quotes, or logos) 6. color (of background, text, graphic elements)

what are task-oriented writing strategies for instructions?

writing strategies, such as active voice, imperative mood, present tense, precise language, and positive terminology, helps you achieve good reader-oriented instructions

step-by-step instructions

Begin each series of steps with a title, goal statement, or introductory clause. For example . . . To place the spare tire onto the car, complete these steps: 1. Hold the spare tire in front of the wheel studs. 2. Align the holes in the spare tire with the studs. 3. Push the spare tire onto the studs. 4. Thread the four lug nuts onto each of the studs. You should generally number your steps instead of using bullets or letters. Numbers will help your readers remember which step they are on. However, if you are writing concise instructions to be displayed on a PDA, cell phone, tablet PC, or other portable device, you may use bullets. You may also use bullets, letters, or Roman numerals for substeps. Be sure to limit the amount of information in each step, and to write each step as a command, using the imperative mode. Write each step as if your audience has just asked, "What do I do now?" State your answer by giving a direct command. Each step you write should require an action of the reader. Keep in mind that the result of an action is not a step; this information should be included in the same step as the action.

Contrast

Use difference to draw readers' eyes to and through your text or publication. Creates readability. In any Web page or magazine, the headline text is always different from the body text. It's often bigger and bolder; it can also be in a different typeface. Applying strong contrasting elements to your text is important because the human eye is drawn to difference, not necessarily size. Some documents, like business letters or academic papers, have fewer contrasting elements, but even line spacing and paragraph breaks help indicate where a related chunk of information begins and ends.

typeface

a collection of fonts, sometimes called a font family (Times New Roman, Arial, Bookman, Georgia, and Garamond) It's important to choose a font (a particular size, style, and weight within a typeface) that fits our purpose. Some, like script and handwriting typefaces, are too hard to read and so aren't appropriate for body text, for example. Some typefaces work well as headlines: Franklin Gothic Condensed and Caslon are two typefaces often used for newspaper headlines. The "font" chosen (size, weight, style—italic, bold, etc.) will be the designer's choice.

a danger

a notice reserved for immediate and severe hazard to the reader or someone else. for example . . . DANGER: Flammable gas! No smoking or open flames.

Instructions

a set of commands that tell readers how to perform a task.