Writing for the web
Writing for the web
Section titled “Writing for the web”Paul reads todos, chunk and session reports and briefings on a screen, often on a phone, between other work. He scans for the answer and the next action. The rules WS-4 to WS-10 make that fast. This page records where each rule comes from, how strong the evidence is, and where BoB departs from the source. (Back to explanation.)
The sources
Section titled “The sources”- Steve Krug, Don’t Make Me Think, Revisited (3rd ed., 2014), and Rocket Surgery Made Easy (2010) for testing. A practitioner’s book: well argued, rarely measured.
- Nielsen Norman Group (NN/g) usability research, starting with How Users Read on the Web (Nielsen, 1997): most test users scanned a page rather than reading it word by word, and concise, scannable, objective text scored far better. Repeated since with eye-tracking, so it is the strongest evidence here.
- Ginny Redish, Letting Go of the Words (2nd ed., 2012): web content is a conversation started by a reader with a task. It turns the research into practice: headings as the reader’s questions, steps as numbered actions, plain words.
What BoB adopts, and how strong the evidence is
Section titled “What BoB adopts, and how strong the evidence is”| Rule | Source | Evidence | Qualified by | What BoB does |
|---|---|---|---|---|
| WS-4 Answer or ask in the first line, ≤ 25 words | NN/g scanning studies; Redish; DS §4.1 | Strong | None material | todo-contract.js warns on a first line over 25 words |
| WS-5 Numbered steps start with a verb, one action each | Redish; Krug | Moderate (practitioner consensus) | None material | todo-contract.js warns on a step starting with an article or pronoun |
| WS-6 Link text says where it goes | NN/g link studies; WCAG 2.4.4 | Strong (also an accessibility requirement) | None material | todo-contract.js warns on link text “here” or “this” |
| WS-7 Plain words, internal terms glossed or linked | Redish; NN/g | Strong for general readers | Expert readers (below) | Simplify the wording, never the identifiers |
| WS-8 Commands and identifiers copyable as-is | BoB’s own todo failures | Operational | — | Review-only |
| WS-9 State visible at a glance | Krug (conventions, visual hierarchy) | Moderate | — | Review-only |
| WS-10 Cut happy talk and instructions about instructions | Krug ch. 5 | Moderate | “Omit needless words” (below) | Review-only |
Headings that make sense alone, lists and tables for parallel items, and front-loaded titles are already owned by the documentation standard (DS §4.1 and §4.2), so they are cited there and not restated.
Where critics and later research qualified the advice
Section titled “Where critics and later research qualified the advice”- The three-click rule is a myth. Nothing shows that users give up after three clicks. NN/g’s own testing found no drop in success or satisfaction with more clicks; what matters is information scent — each click clearly heads toward the goal — and the reader’s confidence. Krug says the same in his second law: the number of clicks matters less than how mindless and unambiguous each one is. BoB: no click or link budget; WS-6 makes each link’s destination obvious instead.
- The F-pattern is a symptom, not a target. NN/g’s 2017 follow-up on its eye-tracking work: readers fall into an F-shaped scan when text has no headings, bullets or bolded keywords to guide them. It is what bad formatting causes. BoB: never lay a page out for the F; format it so the reader doesn’t need it (DS §4.2).
- “Omit needless words” never cuts what the reader needs to decide or act. Krug borrows Strunk and White’s rule. Taken too far, it cuts the context, the reason, the expected output. Redish is explicit that the goal is the words the conversation needs, not the fewest words. BoB: WS-10 cuts happy talk and meta-instructions only; a step keeps its expected output and its “if not, do this” (see the todo-writing skill).
- Small hallway tests find the big problems, not all of them. Krug’s three users a month, and Nielsen’s “five users” argument, find the problems most people hit. Later studies (Faulkner, 2003, among others) showed five users can miss a large share of problems, and results vary widely between samples. BoB: the five-second read on a real artifact (what is this, what do I do?) is a cheap filter for obvious failures, not proof a rule works everywhere.
- BoB’s main reader is an expert operator. Plain-language research is mostly on general audiences. Paul knows the domain; what costs him time is a missing exact value, not a hard word. BoB: simplify the wording, but never remove or paraphrase an exact identifier, command, path or link (WS-7, WS-8).
Checks, and what stays judgment
Section titled “Checks, and what stays judgment”Three rules have cheap mechanical checks in todo-contract.js check: a long first line
(WS-4), a verbless step (WS-5), and “here”/“this” link text (WS-6). They are warnings:
they never make a todo non-conforming, because a heuristic that fails a real todo would
send it to needs-clarification for a word choice. Every other rule is review-only,
checked by a reader, not a regex.