Cognitive psychology for technical communication

Noticing means that information reaches the reader’s attention before anything else can happen.

Technical writers must ask:

• Where is the reader’s attention at this moment?
• What competes with the documentation for attention?
• Does the most important information stand out from the rest?
• Is the warning placed where the reader looks before acting?
• Are there so many warnings that none of them is noticed any more?
• Does the layout separate safety information from ordinary notes?

Attention is selective. Research on selective attention, from Donald Broadbent (1958) and Anne Treisman (1964) onward, shows that people process only a small part of what reaches their senses. Information that does not stand out, or that appears where the reader is not looking, is often not processed at all.

Arien Mack and Irvin Rock (1998) described inattentional blindness, and Daniel Simons and Christopher Chabris (1999) demonstrated it: people miss even striking events when their attention is on a task. Warning research adds habituation — a warning seen too often loses its effect.

For documentation this means: a correct warning that is not noticed protects no one. Placement, salience and restraint are documentation decisions, not design details.

• Noticing is not understanding.
• Visible is not the same as seen.
• More warnings do not mean more attention.
• Bold type is not salience.

Information that is never noticed does not exist for the reader.

Finding means that readers can get from their question to the right place in the documentation.

Technical writers must ask:

• With which question, symptom or word does the reader arrive?
• Do the headings use the reader’s words or the developer’s words?
• Does each heading tell the reader what is behind it?
• Which entry points exist: table of contents, index, search, fault code, symbol?
• Can the reader tell quickly that a page is the wrong one?
• How many steps lie between the question and the answer?

Readers rarely read technical documentation from beginning to end. They search. Peter Pirolli and Stuart Card (1999) described this as information foraging: people follow the information scent of headings, links and labels and give up on a path when the scent weakens.

Scanning is not a failure of the reader. It is the normal way of looking for information. The popular claim that “people don’t read” is too simple: people scan to decide where to read, and then they read closely.

For documentation this means: the structure must work for someone who enters in the middle, with their own words and with little patience.

• Finding is not reading.
• A table of contents is not a search strategy.
• A heading is a promise about what follows.

Information that cannot be found is as useless as information that was never written.

Orienting means that readers recognise where they are, what this information is for and whether it applies to their product and situation.

Technical writers must ask:

• Does the reader know which product, variant and operating mode this page covers?
• Does the page say what kind of information it is?
• Is it clear what the reader should have read or done before?
• Does the layout group what belongs together?
• Does the reader see the structure before the details?
• Can a reader who arrives from search tell where this page sits in the whole?

Readers understand new information through what they already know. Frederic Bartlett (1932) described schemas as organised prior knowledge; John Bransford and Marcia Johnson (1972) showed that the same passage is far easier to understand and remember when readers know its topic in advance. David Ausubel (1960) proposed advance organizers for this reason.

Perception also groups what it sees. The Gestalt principles described by Max Wertheimer (1923) — proximity, similarity, common region — decide which elements of a page a reader takes as one unit.

For documentation this means: context, validity and the type of information must be visible before the content, and the layout must show the structure the text intends.

• Orientation is not navigation.
• A page without context forces the reader to guess.
• Validity is information, not metadata for the writer only.

Readers who know where they are can understand what they read.

Understanding means that readers construct the intended meaning from the text — not just decode its words.

Technical writers must ask:

• Which inferences does the text leave to the reader?
• Which of these inferences can the reader actually make?
• Are terms used consistently, or does one thing have several names?
• Are causes, conditions and consequences stated explicitly?
• Does an example show what the abstract statement means?
• Would a reader with less prior knowledge reach the same meaning?
• Is the text readable in the reader’s language level and, if needed, in translation?

Reading comprehension is construction. Teun van Dijk and Walter Kintsch (1983) distinguished the text itself from the situation model that readers build from it; Kintsch’s construction-integration model (1988) describes how readers combine the text with their knowledge and fill gaps by inference.

Inferences cost effort and can go wrong. Readers with less prior knowledge make fewer of them, and readers with the wrong prior knowledge make the wrong ones. Readability formulas measure word and sentence length; they do not measure whether the intended situation model is reached.

For documentation this means: what the reader must infer must be inferable, and what must not be misunderstood must be said explicitly.

• Understanding is not decoding.
• A short sentence is not automatically a clear one.
• What the writer finds obvious, the reader must infer.

Text gives the material. The reader builds the meaning.

Modelling means that readers build a working model of the product or system that lets them predict what will happen.

Technical writers must ask:

• Which model of the system does the reader bring along?
• Where does that model differ from how the system actually works?
• Which concept must the reader grasp before a task makes sense?
• Does the documentation explain states, modes and their transitions?
• Can the reader predict what the system will do after their action?
• Does a diagram show the relationships the text describes?

Philip Johnson-Laird (1983) described mental models as internal representations that people use to reason and predict. Donald Norman (1983, 1988) applied the idea to products: the designer has a model, the user forms another, and the only bridge between them is the system image — the product, its interface and its documentation.

Norman also described the gulfs of execution and evaluation: the distance between what users want to do and what the system lets them do, and between what the system shows and what users can interpret. Documentation is part of the system image. It can narrow these gulfs or widen them.

For documentation this means: concept information is not background. It builds the model that makes tasks understandable and errors predictable.

• A procedure is not a model.
• A wrong model survives correct steps.
• Concept information belongs before the task, not after the fault.

Readers act on their model of the system, not on the system itself.

Holding means that the information a reader needs at one moment fits into working memory.

Technical writers must ask:

• How much must the reader keep in mind to perform this step?
• Does one step contain several actions?
• Must the reader look back to an earlier page, table or figure?
• Are labels placed on the figure or in a separate legend?
• Are values, settings and limits given where they are needed?
• Which information can be grouped into a meaningful chunk?
• What is extra effort caused only by the presentation?

Alan Baddeley and Graham Hitch (1974) described working memory as a limited system for holding and processing information. George Miller’s “magical number seven, plus or minus two” (1956) is often quoted as a rule for list length; Nelson Cowan (2001) concluded that the limit is closer to about four chunks — and that what counts as a chunk depends on prior knowledge. Neither is a rule for the number of steps in a procedure.

John Sweller’s cognitive load theory (1988) distinguishes the load that belongs to the task from the load caused by its presentation. Paul Chandler and Sweller (1991) showed the split-attention effect: when readers must combine a figure and a separate text in their head, learning suffers.

For documentation this means: the decisive question is not how many steps a procedure has, but how much each step asks the reader to hold at once.

• Seven plus or minus two is not a rule for steps.
• Short steps are not automatically light steps.
• Working memory is not a storage place for the manual.

What the reader must hold in mind, the documentation should hold on the page.

Remembering means that what must be known later is either learned reliably or available at the moment it is needed.

Technical writers must ask:

• Which information must the reader know by heart?
• Which information only needs to be recognised when seen?
• Which intention must the reader remember at a later moment?
• Where will an interruption occur, and how does the reader find their place again?
• Can a reminder be placed where the action takes place?
• Which information belongs in training rather than in the manual?

Recognition is easier than recall: people identify information they see far more reliably than they retrieve it from memory. This is why interfaces and job aids that show options outperform instructions that must be remembered.

Prospective memory — remembering to do something later — is especially fragile. Gilles Einstein and Mark McDaniel (1990) studied how such intentions are triggered by cues. Erik Altmann and Gregory Trafton (2002) described the cost of resuming a task after an interruption, the resumption lag.

For documentation this means: important intentions need a cue at the right moment, and procedures that are often interrupted need clear points where the reader can pick them up again.

• Read once is not remembered.
• Training is not a substitute for information at the point of use.
• An interruption is a foreseeable part of the task.

What the reader must not forget, the documentation should not leave to memory.

Deciding means that readers choose the right action — including the decision not to act — on the basis of the information given.

Technical writers must ask:

• Which decision does the reader face at this point?
• Are the criteria for the decision stated, or must the reader guess them?
• Are the consequences of each option visible?
• Does the reader know when to stop and call someone?
• Does the wording make a risk seem smaller or larger than it is?
• Which shortcut will a reader under pressure be tempted to take?

People do not decide like calculators. Amos Tversky and Daniel Kahneman (1974) described heuristics and biases — rules of thumb that are usually efficient and sometimes systematically wrong. Herbert Simon (1956) described satisficing: people choose the first option that seems good enough.

Mica Endsley (1995) described situation awareness in three levels: perceiving the elements of a situation, understanding their meaning and projecting what will happen next. Paul Slovic’s research on risk perception (1987) shows that people judge risk by familiarity and control, not only by probability.

For documentation this means: decision criteria, consequences and stop criteria must be explicit. A cognitive argument never replaces the risk assessment; it only helps to communicate its results so that they can be used.

• Information is not a decision.
• A familiar risk is not a small risk.
• Knowing when to stop is part of the task.

Documentation that leaves the decision criteria unsaid leaves the decision to chance.

Acting means that readers carry out the intended action correctly, in the right order and with the right result.

Technical writers must ask:

• Is the action stated in a form the reader can perform directly?
• Does each step say what the reader does and what they should observe?
• Is the behaviour skill-based, rule-based or knowledge-based at this point?
• Where is the reader likely to act from habit instead of reading?
• Which critical step would benefit from a checklist or confirmation?
• Does the reader know when the task is complete?

Jens Rasmussen (1983) distinguished skill-based, rule-based and knowledge-based behaviour. Skilled routine actions run with little conscious control; rules are applied to familiar situations; knowledge-based reasoning is needed for new problems and is slow and error-prone. Documentation speaks to each level differently.

Research on checklists in aviation, for example by Asaf Degani and Earl Wiener (1990), shows that checklists support critical sequences when they are short, ordered and designed for the situation in which they are used.

For documentation this means: a procedure must fit the level of behaviour at which the task is performed, and it must show the reader the result of each action.

• Reading a step is not performing it.
• A feature description is not an instruction.
• A checklist is not a shortened manual.

Instructions succeed only when the reader can act on them.

Recovering means that readers notice that something went wrong, understand what kind of problem it is and return to a safe, working state.

Technical writers must ask:

• How does the reader notice that something went wrong?
• Does the troubleshooting start from the symptom the reader actually sees?
• Does it distinguish an action that was forgotten from a wrong plan?
• Which recovery step is safe under time pressure?
• When must the reader stop and escalate?
• What must be checked before a restart?
• Which unsafe workaround is foreseeable after a fault?

James Reason (1990) distinguished slips and lapses — the right intention carried out wrongly or forgotten — from mistakes, where the plan itself is wrong. Donald Norman (1981) had classified slips before. The types need different help: slips need design and feedback, lapses need cues, mistakes need a better model and better decision information.

Errors are not exceptions in technical work. They are foreseeable. Recovery is the part of the task where stress is highest and patience lowest, and where the gulf of evaluation decides whether the reader understands what the system is telling them.

For documentation this means: troubleshooting and recovery information must be written for a reader under stress. It supports the safety measures defined in the risk assessment; it does not replace them.

• An error is not a failure of the reader.
• A slip is not a mistake.
• A fault message is not an explanation.

Documentation proves its value when something goes wrong.