The Explanation LabAll 20 lessons

14 STRUCTURE · Information shaped like the task

Write for the task.

You will learn how to organize instructions around what the user is trying to do, using the shape IEC/IEEE 82079-1 describes. It takes 3 minutes.

The problem

Your goal: make one espresso. The steps are all in the manual, but they're scattered across sections about the parts.

EXAMPLE MANUAL · CONTENTS

  1. 1 Housing and panels
  2. 2 Water system
  3. 3 Pump module
  4. 4 Group head
  5. 5 Portafilter
  6. 6 Control panel
  7. 7 Steam wand
  8. 8 Specifications
  1. 2.4 Fill the tank
  2. 6.1 Wait for the ready light
  3. 5.2 Dose 18 g, tamp level
  4. 4.1 Lock the portafilter
  5. 6.3 Press brew
  6. 4.6 Stop at about 36 g

To make one espresso you visit 6 sections, in this order. Sections visited: 2.4, 6.1, 5.2, 4.1, 6.3, 4.6.

The manual is organized the way the machine is built. The reader is organized around a goal.

Watch the clip

The clip follows the reader through the manual, then rebuilds the same content around the task. Watch the list on the right: it names each piece of the new shape.

28 seconds · lesson 14 of 20 from the full video

The name for it

THE NAME FOR IT

IEC/IEEE 82079-1 Information for use

IEC/IEEE 82079-1 · Preparation of information for use of products

Organize instructions around what the user needs to do: goal, prerequisites, actions, results, completion.

The same content, shaped for the task

EXAMPLE MANUAL · ONE TASK, ONE PAGE

GOAL

Make one double espresso.

BEFORE YOU START

Water tank filled · Ready light steady (about 20 min) · 18 g finely ground coffee

  1. Put 18 g of ground coffee in the portafilter. Tamp it level.YOU SHOULD SEE: The surface is flat.
  2. Lock the portafilter into the group head.YOU SHOULD SEE: The handle points toward you.
  3. Put a cup under the spouts. Press the brew button.YOU SHOULD SEE: Coffee flows in 5 to 8 seconds.
  4. At about 36 g in the cup, press the brew button again.YOU SHOULD SEE: The flow stops.

DONE

You have one double espresso.

NEXT

Knock out the used coffee. Rinse the portafilter.

Every step says what to do, then what you should see. You never leave the page.

Rewrite one of your own procedures

Goal: One procedure from your documentation, rewritten around the task.

Before you start: Pick a task people often ask for help with. Have the current documentation open.

  1. Write the goal as the user would say it. "Make one double espresso," not "Brewing functions." You should see: one short sentence a user would recognize as their goal.
  2. List what must be true before step 1. Tools, materials, settings, time. You should see: a "before you start" list. Nothing in it should surprise the user halfway through.
  3. Gather every action, from wherever it lives in the docs. Put them in the order the user does them. You should see: numbered steps that each start with a verb.
  4. After each step, write what the user should see. A light, a sound, a reading, a screen. You should see: a result line under every step the user could get wrong.
  5. Say when they're done, and what's next. You should see: a "done" line and a pointer to the next likely task.

Done: You have one task page. Test it on someone who hasn't seen the old version.

Next: Do the same for the next most-asked task. Link the old part-by-part sections from the task pages as reference.

TAKEAWAY

Write for the task,
not for the parts list.

Ask your agent

PROMPT
Rewrite the instructions below as one task, in the shape of IEC/IEEE 82079-1:
GOAL (in the user's words), BEFORE YOU START (prerequisites), numbered STEPS,
and under each step a "You should see" line with the observable result,
then DONE (how the user knows they finished) and NEXT (the likely next task).
Pull steps from wherever they appear in the source and put them in the order the user does them.
Flag any step where the source doesn't say what the user should see.

Instructions:
[paste here]

What good output looks like: one page with a goal at the top, a result under each step, and a list of the gaps it found in the original.

Sources