Writing Instructional Texts

Miriam Brandel

Normed Communication

Language in:

• Law

• Science

• Medicine

• Advertising

• Etc.

• Instruction Manuals/ How-to Instructions

e.g. for technical equipment, software installation, etc.

• Prescribing information

• Etc.

Goal: intelligibility

Instructions are…

• A tool for consumers to use or do something

• Specially designed to provide an adequate tool for the (possible) consumer

• Documents which are comparable not to an effort of writing but of engineering

‘Good’ Instructions…

• Describe the actions/procedures necessary to perform a task (in a way the consumer understands)

• Explain how a product works and applications for which it is used

• Describe how the product may be misused

• Provide sufficient safety information (e.g. warn about possible hazards)

• Encourage consumers to act in a safe way

• Meet legal obligations for duty to warn

• Meet regulatory requirements/standards for giving certain information

How can Instructions Fail?

Job application form question:

‘Give previous experience with dates’.

One candidate’s reply:

‘Moderately successful in the past, but I am now happily married!’

Instructions (Can) Fail When…

• The product is poorly designed

• Possible hazards are difficult to perceive or control

• Procedures are too complex for the consumer to perform

BUT also when

• Poor or uninformed decisions have been made in the different stages of the development process!

Writing Instructional Texts (James Hartley)

• Pre-Design- Planning stage

• Design- Producing the document

• Post-Design- Testing/Editing the document

Pre-Design

• Making decisions about the scope and purpose of the document; i.e. answering the following questions:

- what are the goals of the instructions?

- who is the audience?

- what are the constraints?

Goals of the Instructions

• Define the scope of your instructions

• Identify key tasks that users must perform based on the scope of the instructions

• Define specific and measurable criteria for success for each key task

• Identify all reasonably foreseeable hazards associated with the product

• Specify the knowledge and skills required to successfully perform each task with your product

• Find out how consumers are likely to use the product under real-world conditions

Qualitative Techniques to Explore How Consumers may Use a Product

• Focus groups

• Usability testing

• Observational methods

• Affordance analyses

Who is the Audience

• Identify and characterize the population of reasonably foreseeable users of the product and instructions

• Find out consumers’ attitudes and beliefs about the product

• Consider the different needs and abilities of novice (beginner) and expert users

• Consider the needs/abilities of the elderly (target age groups)

• Consider the needs/abilities of non-English-literate users

Design Alternatives to Communicate to Non-English-Literate Users

• Translate the full text of the instructions

• Make alternative language versions of the instructions available (upon request)

• Provide safety warnings in multiple languages, but the rest of the instructions in English

• Use diagrams and graphics to illustrate actions; rely less on text

What are the Constraints?

• Identify:

- government and legal regulations…

- voluntary standards and industry-recommended practices…

…that relate to instructions, warnings and other required consumer information for the specific type of product

• Identify requirements imposed by the manufacturer

Design

• Producing the document; i.e.

- writing the appropriate text

- organizing/structuring the text

- presenting the text in a clear and simple language

- using appropriate illustrative materials

Guidelines for Writing Instructional Texts

Organizing Text

1) Titles

2) Summaries

3) Headings

4) Questions

5) Sequencing

6) Sequencing lists

7) Signaling

8) Typographic cueing

Text Factors

• Paragraph length

• Sentence length

• Word length

• Clarifying text

• Text difficulty

• Difficult short sentences

• Ambiguities

• Clarifying numbers

• Reference numbers

• Footnotes

Exercises

Sources

Hartley, James. 1985. Designing Instructional Text. pp. 48-60

Smith, Singer. Developing Consumer Product Instructions. (Sections 1,2 & Checklist)

http://www.cpsc.gov/LIBRARY/FOIA/foia04/os/guide.pdf