Reader-facing Writing
A reader-facing artifact has one job, a page budget, and a figure wherever the content has a shape. First drafts run two to three times too long because they answer every question instead of the reader's; the skeletons below set the size, and the closing pass deletes down to it.
Workflow
- Fix the reader and the job. Decide who reads, what they already know, and whether they must decide, do, look up, or understand. One artifact, one job; a second job becomes a note or a linked artifact. Do not label the audience, purpose, or writing process in the artifact: no "for the on-call lead" in a title, no background section about the document itself (context about the system is content and stays); the opening starts with what the reader came for. Preserve a structure, framework, or correction list the user supplied, and treat requested prominence as a delivery contract, not a footnote. For a large subjective rewrite with no target tone, structure, or ordering, show a compact outline or 2-3 options before executing.
- Pick the skeleton and its budget from the table below. The budget is a ceiling for the main path; everything the main path does not need goes to one named detail layer (appendix, linked page, click-to-open), never to a second overview.
- Draft each section as one screen: a claim-led heading, the figure or table that carries the relationship, at most five sentences that argue from it, and a link to detail. Choose the figure with the form table, and its rendering by the target medium: Markdown on a code host renders static images, Mermaid, and GIF; an HTML page or deck can also carry video, step-by-step reveal, and click-to-open evidence, with a static fallback for each. Read references/visuals-and-decks.md when the artifact carries a chart, diagram, screenshot, before/after pair, recording, GIF, deck, or HTML page.
- Preserve source truth. Keep the source framework when condensing; use source wording for numbers, names, owners, and dates; keep observation, self-report, inference, and unknowns distinct, and mark unknowns TBD or cut them (a TBD is resolved or removed before a view-only audience sees it). When shipped and planned items share a list, tag maturity inline. Keep the scope that qualifies a claim (environment, period, population, excluded cases) beside it, and keep it there when the claim is compressed into a table: "79 nodes" measured on a sampled development cluster, placed unqualified in a delivery-shape matrix, read as the product's delivery size and had to be re-labelled as sample data. Never assert a capability or track record of your own side you only inferred, and never fill a length quota with invented detail. Read references/shaping-checklist.md when sources conflict, mix delivered with planned, or were written for a different audience.
- Write plain sentences with references/prose-style.md: active voice, one idea per sentence, no announcements, no meta-commentary, terms calibrated to the reader.
- Delete to budget with references/revision-pass.md: drop every sentence whose removal loses no fact and every visual whose removal makes no relationship harder to see, then run the entry-point, findability, and doing-path checks. The delete pass never removes prerequisites, commands, decision points, rollback, or done checks from a how-to, and leaves bold only on the few decisions, dates, or numbers a skimmer must catch. Report what stays unverified; an author reread never proves a human understood it.
Skeletons and budgets
Pick by the reader's job. Sections are in order; a section the material cannot fill is dropped, not padded. One page means about 400-500 words of Markdown or one screen without scrolling.
| Artifact |
Skeleton (in order) |
Main-path ceiling |
Default figure |
| Decision brief |
Recommendation and why now; options on the same fields; what is asked of the reader |
1 page |
Comparison table |
| Incident review |
Impact in one line; root cause and contributing factors; what was done; what remains, with owner and date; timeline in the detail layer |
1 page |
Timeline table |
| Design doc / RFC |
Context and scope; goals and non-goals; design; alternatives and their trade-offs; cross-cutting concerns; rollout; open questions |
3 pages; 1 page for an incremental change |
Context diagram when the change touches more than one component; a sequence diagram per flow that crosses a boundary |
| How-to / runbook |
Trigger; prerequisites; numbered steps, each with its check; stop, rollback, and whom to escalate to; done criterion |
12 steps; split beyond that |
Screenshot of the decisive state, or a state diagram |
| Action plan / checklist |
One item per line: verb-first action, single owner, absolute date or concrete phase, done criterion; items parallel and in one order (time, structure, or importance); open items marked TBD, never invented |
One screen |
Table |
| Status report |
Takeaway; blockers and risks; each number with what it counts and its basis; what changes for the reader; next actions with owner and date |
1 page |
None; a table when several metrics recur, sorted bars only for a ranking |
| Multi-topic brief or meeting pre-read |
Agenda naming each topic; one section per topic; next actions per responsible role |
1 screen per topic |
One figure per topic where the topic has a shape |
| README |
What it is in one line; quick start that works as pasted; one minimal example; links to the deeper docs |
1 screen before the first link |
Screenshot or GIF of the result, only when the result is visual |
| Release notes |
What changed for the user, grouped by impact, breaking changes and required upgrade actions first; internal refactors omitted |
1 line per change |
None |
| Meeting notes |
Decisions made; actions with owner and date; open questions; no transcript |
1 screen |
Table |
| Change handoff note (for QA, ops, or the next owner) |
What changed, deletions included, one line each, named by the behaviour and not by merge request, class, or review round; what the user can perceive; how it is designed, so a tester can derive cases; what to test, in priority order; what is not a defect; what must be prepared; what the developer has verified; who still has to confirm what; what to watch at rollout; developer contact |
1 page; details as a linked appendix |
Table of changes; a diagram only for a flow the tester cannot infer |
| Notice |
The change, who is affected and who is not, when |
One paragraph |
None |
| Reference / lookup, API reference |
Searchable headings; signature or field, parameter table, one example, errors; no narrative |
No prose beyond a lead line |
Table |
| Agent instruction file (AGENTS.md, CLAUDE.md) |
Commands, paths, boundaries, hard rules |
Delete test on every line |
None |
A deck follows the same skeleton as its subject, one claim per slide as the headline with the proving visual beneath it; a new audience gets one slide on what the subject is before any implication.
Form by content shape
The figure exists to make the content easier to understand, so the content decides. If one plain sentence carries the point, the sentence wins and no figure is added; a figure that restates a sentence is the same redundancy in a second medium. Default to a figure when the content is a structure, a flow, a sequence, a hierarchy, a comparison on the same fields, or change over time, because those shapes cost the reader more to rebuild from prose than to read from a picture. Keep to a sentence when the content is one conclusion or one or two numbers, and to a table when the reader will look values up.
| Information the reader needs |
Form |
| One conclusion or a few facts |
A sentence or a single large figure |
| Exact values or repeated fields across items |
A table |
| Several options compared on the same fields |
An aligned comparison table |
| Ranking on one measure |
Bars sorted by value, labelled directly |
| Named events or milestones over time |
A timeline |
| Numeric change over time |
A line chart |
| Interaction over time between parties |
A sequence diagram |
| Branched process, decision path, proven causal chain |
A flowchart |
| Parent-child structure |
A tree, never a mind map |
| Part of a whole |
A stacked bar |
| Distribution of many values |
A histogram |
| Components and their boundaries |
A context or architecture diagram |
| Proof that something occurred |
The real screenshot, record, or result |
- Title every figure with its takeaway and state its basis. Under it, write only what the figure cannot carry: the conclusion, the mechanism behind one arrow, or a caveat. A sentence that retells the arrows, rows, or steps in order is deleted, even when it feels like a courtesy to the reader.
- An arrow, a step number, or an operator is a factual claim of sequence, causation, or arithmetic. Connect only items whose data proves that relationship; keep independent metrics separate and labelled as not comparable.
- Draw the diagram in the form its medium renders best: Mermaid or the project's diagram format in Markdown on a code host, where the source lives beside the content; authored SVG or HTML geometry in an HTML page; native shapes in a deck. A Mermaid render pasted into an HTML page or a slide is auto-layout quality in a medium that can carry authored geometry. Keep one diagram to one question at one altitude and at most 15 nodes; split rather than crowd. Companion skills, when available, own the rest:
technical-diagramming the technical model, geometry, and validation of a diagram; verification browser and rendered-surface acceptance; artifact-hygiene placement, redaction, packaging, and handoff. This skill owns whether the reader needs the visual, its question, and its takeaway. If a companion is unavailable, use only the fallback in references/visuals-and-decks.md and report what stays unverified.
- Two or three counts with no series, distribution, or comparison stay as a sentence or as large directly labelled figures with their basis, even when the request asks to make them visual; a proportion bar or card layout for two numbers is a chart the data has not earned, and building it as HTML is the same chart at a higher cost.
- A numbered procedure is already a sequence: do not add a flowchart that restates its steps. Give a how-to a figure only for a branch the steps cannot show in order, or a screenshot of the state the operator must recognize.
Examples
Incident review. The source: search returned timeouts from 14:02 to 14:31; a cache TTL had been deployed as 0 instead of 300; rolling back the config restored service; the permanent fix is merged but not released; Owner B releases it on September 3.
Before, scaffolding around 40 words of fact:
This document is intended for the on-call lead and summarizes the incident that occurred this afternoon. Background: at 14:02 the search service began returning timeouts. The team investigated and, after a period of analysis, identified that the cache configuration was incorrect. A rollback was performed at 14:31, after which service was restored. Root cause analysis showed the TTL was 0 instead of 300. Next steps: the permanent fix has been merged and will be released. Summary: the incident lasted 29 minutes and the root cause has been identified and will be addressed.
After:
Search was down 29 minutes (14:02-14:31); the permanent fix is merged but not released.
Root cause: cache TTL deployed as 0 instead of 300. Rolling back the config restored service.
| Item |
Owner |
Date |
| Release the TTL fix |
Owner B |
Sep 3 |
Call chain for reviewers. The source describes an upload service that calls a scan service synchronously, scan calls a metadata service, and metadata writes to a queue; when scan is slow, each upload worker stays blocked, and the worker pool empties.
Before: the four hops and the failure written as one paragraph, which every reviewer reads twice.
After: a sequence diagram with a one-line takeaway and the one sentence the diagram cannot carry.
A slow scan blocks an upload worker for the whole call, so a scan slowdown empties the worker pool.
sequenceDiagram
Client->>Upload: file
Upload->>Scan: scan (sync, worker blocked)
Scan->>Metadata: lookup
Metadata->>Queue: enqueue
Scan-->>Upload: result (slow)
Note over Upload: 32 workers, all waiting on Scan
Scan's latency is inherited by every caller because the upload-to-scan call is synchronous; making that call asynchronous is the change under review.
Change handoff note. A change that removed an upload endpoint, added a rate limit on third-party downloads, and moved files to a new path went through three descriptions. Version one listed merge-request numbers, class names, and four review rounds; the tester could not find what to test, and none of those identifiers survive into the note. Version two was rewritten for the tester and lost the list of what changed. Version three:
| Change |
Kind |
Visible to users |
/upload/legacy removed |
Deletion |
Old clients get 404; new path unchanged |
| Third-party downloads rate-limited (20/min per tenant) |
Behaviour |
Bursts above the limit wait, not fail |
Files served from /appdownload/ alongside the old path |
Path |
Both URLs work until the next release |
Design: the service probes the target before uploading and reuses an existing identical file, so a retry of a published file never truncates it. Test first: upload the same package twice and interrupt one; then a burst of 30 downloads; then the old URL. Not a defect: the old URL still serving for one release.
Notice. Two numbers and a date do not need a title, a background section, or next steps:
Old login closes Friday 18:00. Signed-in users are unaffected. Anyone not moved to the new login by then cannot sign in on Monday.
Agent-facing instruction files
When the reader is an agent that acts on the file (AGENTS.md, CLAUDE.md, a rules doc), keep only commands, paths, boundaries (what may and may not change), and hard rules stated as their executable part; cut mission, ownership, vision, process asides, and slogans. Delete every line whose removal would not change what the agent does, and title the file with the repository name.
1---2name: reader-facing-writing3description: Write or revise reader-facing documents, plans, reports, proposals, specs, checklists, Markdown, HTML decks, dashboards, decision briefs, and agent-facing instruction files (AGENTS.md, CLAUDE.md) — and decide what each page or slide says and in what form, whether that is prose, a diagram, a screenshot, a before/after comparison, or a long screen recording trimmed and sped up into demo material an audience can actually follow. Use when content is meant for humans or agents to read, decide from, act on, review, or reuse, including compacting source material without losing its framework, when a broad rewrite is asked for with no target tone, structure, or ordering given and the target has to be agreed before executing, when a change has to land across mirrored artifacts such as a script and its rendered deck, and when turning raw captures into material that carries a point to an audience. A one-pager or dashboard counts when its job is to carry a conclusion to a named audience, charts included.4---56# Reader-facing Writing78A reader-facing artifact has one job, a page budget, and a figure wherever the content has a shape. First drafts run two to three times too long because they answer every question instead of the reader's; the skeletons below set the size, and the closing pass deletes down to it.910## Workflow11121. Fix the reader and the job. Decide who reads, what they already know, and whether they must decide, do, look up, or understand. One artifact, one job; a second job becomes a note or a linked artifact. Do not label the audience, purpose, or writing process in the artifact: no "for the on-call lead" in a title, no background section about the document itself (context about the system is content and stays); the opening starts with what the reader came for. Preserve a structure, framework, or correction list the user supplied, and treat requested prominence as a delivery contract, not a footnote. For a large subjective rewrite with no target tone, structure, or ordering, show a compact outline or 2-3 options before executing.132. Pick the skeleton and its budget from the table below. The budget is a ceiling for the main path; everything the main path does not need goes to one named detail layer (appendix, linked page, click-to-open), never to a second overview.143. Draft each section as one screen: a claim-led heading, the figure or table that carries the relationship, at most five sentences that argue from it, and a link to detail. Choose the figure with the form table, and its rendering by the target medium: Markdown on a code host renders static images, Mermaid, and GIF; an HTML page or deck can also carry video, step-by-step reveal, and click-to-open evidence, with a static fallback for each. Read [references/visuals-and-decks.md](references/visuals-and-decks.md) when the artifact carries a chart, diagram, screenshot, before/after pair, recording, GIF, deck, or HTML page.154. Preserve source truth. Keep the source framework when condensing; use source wording for numbers, names, owners, and dates; keep observation, self-report, inference, and unknowns distinct, and mark unknowns TBD or cut them (a TBD is resolved or removed before a view-only audience sees it). When shipped and planned items share a list, tag maturity inline. Keep the scope that qualifies a claim (environment, period, population, excluded cases) beside it, and keep it there when the claim is compressed into a table: "79 nodes" measured on a sampled development cluster, placed unqualified in a delivery-shape matrix, read as the product's delivery size and had to be re-labelled as sample data. Never assert a capability or track record of your own side you only inferred, and never fill a length quota with invented detail. Read [references/shaping-checklist.md](references/shaping-checklist.md) when sources conflict, mix delivered with planned, or were written for a different audience.165. Write plain sentences with [references/prose-style.md](references/prose-style.md): active voice, one idea per sentence, no announcements, no meta-commentary, terms calibrated to the reader.176. Delete to budget with [references/revision-pass.md](references/revision-pass.md): drop every sentence whose removal loses no fact and every visual whose removal makes no relationship harder to see, then run the entry-point, findability, and doing-path checks. The delete pass never removes prerequisites, commands, decision points, rollback, or done checks from a how-to, and leaves bold only on the few decisions, dates, or numbers a skimmer must catch. Report what stays unverified; an author reread never proves a human understood it.1819## Skeletons and budgets2021Pick by the reader's job. Sections are in order; a section the material cannot fill is dropped, not padded. One page means about 400-500 words of Markdown or one screen without scrolling.2223| Artifact | Skeleton (in order) | Main-path ceiling | Default figure |24| --- | --- | --- | --- |25| Decision brief | Recommendation and why now; options on the same fields; what is asked of the reader | 1 page | Comparison table |26| Incident review | Impact in one line; root cause and contributing factors; what was done; what remains, with owner and date; timeline in the detail layer | 1 page | Timeline table |27| Design doc / RFC | Context and scope; goals and non-goals; design; alternatives and their trade-offs; cross-cutting concerns; rollout; open questions | 3 pages; 1 page for an incremental change | Context diagram when the change touches more than one component; a sequence diagram per flow that crosses a boundary |28| How-to / runbook | Trigger; prerequisites; numbered steps, each with its check; stop, rollback, and whom to escalate to; done criterion | 12 steps; split beyond that | Screenshot of the decisive state, or a state diagram |29| Action plan / checklist | One item per line: verb-first action, single owner, absolute date or concrete phase, done criterion; items parallel and in one order (time, structure, or importance); open items marked TBD, never invented | One screen | Table |30| Status report | Takeaway; blockers and risks; each number with what it counts and its basis; what changes for the reader; next actions with owner and date | 1 page | None; a table when several metrics recur, sorted bars only for a ranking |31| Multi-topic brief or meeting pre-read | Agenda naming each topic; one section per topic; next actions per responsible role | 1 screen per topic | One figure per topic where the topic has a shape |32| README | What it is in one line; quick start that works as pasted; one minimal example; links to the deeper docs | 1 screen before the first link | Screenshot or GIF of the result, only when the result is visual |33| Release notes | What changed for the user, grouped by impact, breaking changes and required upgrade actions first; internal refactors omitted | 1 line per change | None |34| Meeting notes | Decisions made; actions with owner and date; open questions; no transcript | 1 screen | Table |35| Change handoff note (for QA, ops, or the next owner) | What changed, deletions included, one line each, named by the behaviour and not by merge request, class, or review round; what the user can perceive; how it is designed, so a tester can derive cases; what to test, in priority order; what is not a defect; what must be prepared; what the developer has verified; who still has to confirm what; what to watch at rollout; developer contact | 1 page; details as a linked appendix | Table of changes; a diagram only for a flow the tester cannot infer |36| Notice | The change, who is affected and who is not, when | One paragraph | None |37| Reference / lookup, API reference | Searchable headings; signature or field, parameter table, one example, errors; no narrative | No prose beyond a lead line | Table |38| Agent instruction file (AGENTS.md, CLAUDE.md) | Commands, paths, boundaries, hard rules | Delete test on every line | None |3940A deck follows the same skeleton as its subject, one claim per slide as the headline with the proving visual beneath it; a new audience gets one slide on what the subject is before any implication.4142## Form by content shape4344The figure exists to make the content easier to understand, so the content decides. If one plain sentence carries the point, the sentence wins and no figure is added; a figure that restates a sentence is the same redundancy in a second medium. Default to a figure when the content is a structure, a flow, a sequence, a hierarchy, a comparison on the same fields, or change over time, because those shapes cost the reader more to rebuild from prose than to read from a picture. Keep to a sentence when the content is one conclusion or one or two numbers, and to a table when the reader will look values up.4546| Information the reader needs | Form |47| --- | --- |48| One conclusion or a few facts | A sentence or a single large figure |49| Exact values or repeated fields across items | A table |50| Several options compared on the same fields | An aligned comparison table |51| Ranking on one measure | Bars sorted by value, labelled directly |52| Named events or milestones over time | A timeline |53| Numeric change over time | A line chart |54| Interaction over time between parties | A sequence diagram |55| Branched process, decision path, proven causal chain | A flowchart |56| Parent-child structure | A tree, never a mind map |57| Part of a whole | A stacked bar |58| Distribution of many values | A histogram |59| Components and their boundaries | A context or architecture diagram |60| Proof that something occurred | The real screenshot, record, or result |6162- Title every figure with its takeaway and state its basis. Under it, write only what the figure cannot carry: the conclusion, the mechanism behind one arrow, or a caveat. A sentence that retells the arrows, rows, or steps in order is deleted, even when it feels like a courtesy to the reader.63- An arrow, a step number, or an operator is a factual claim of sequence, causation, or arithmetic. Connect only items whose data proves that relationship; keep independent metrics separate and labelled as not comparable.64- Draw the diagram in the form its medium renders best: Mermaid or the project's diagram format in Markdown on a code host, where the source lives beside the content; authored SVG or HTML geometry in an HTML page; native shapes in a deck. A Mermaid render pasted into an HTML page or a slide is auto-layout quality in a medium that can carry authored geometry. Keep one diagram to one question at one altitude and at most 15 nodes; split rather than crowd. Companion skills, when available, own the rest: `technical-diagramming` the technical model, geometry, and validation of a diagram; `verification` browser and rendered-surface acceptance; `artifact-hygiene` placement, redaction, packaging, and handoff. This skill owns whether the reader needs the visual, its question, and its takeaway. If a companion is unavailable, use only the fallback in [references/visuals-and-decks.md](references/visuals-and-decks.md) and report what stays unverified.65- Two or three counts with no series, distribution, or comparison stay as a sentence or as large directly labelled figures with their basis, even when the request asks to make them visual; a proportion bar or card layout for two numbers is a chart the data has not earned, and building it as HTML is the same chart at a higher cost.66- A numbered procedure is already a sequence: do not add a flowchart that restates its steps. Give a how-to a figure only for a branch the steps cannot show in order, or a screenshot of the state the operator must recognize.6768## Examples6970**Incident review.** The source: search returned timeouts from 14:02 to 14:31; a cache TTL had been deployed as 0 instead of 300; rolling back the config restored service; the permanent fix is merged but not released; Owner B releases it on September 3.7172Before, scaffolding around 40 words of fact:7374> This document is intended for the on-call lead and summarizes the incident that occurred this afternoon. Background: at 14:02 the search service began returning timeouts. The team investigated and, after a period of analysis, identified that the cache configuration was incorrect. A rollback was performed at 14:31, after which service was restored. Root cause analysis showed the TTL was 0 instead of 300. Next steps: the permanent fix has been merged and will be released. Summary: the incident lasted 29 minutes and the root cause has been identified and will be addressed.7576After:7778> **Search was down 29 minutes (14:02-14:31); the permanent fix is merged but not released.**79>80> Root cause: cache TTL deployed as 0 instead of 300. Rolling back the config restored service.81>82> | Item | Owner | Date |83> | --- | --- | --- |84> | Release the TTL fix | Owner B | Sep 3 |8586**Call chain for reviewers.** The source describes an upload service that calls a scan service synchronously, scan calls a metadata service, and metadata writes to a queue; when scan is slow, each upload worker stays blocked, and the worker pool empties.8788Before: the four hops and the failure written as one paragraph, which every reviewer reads twice.8990After: a sequence diagram with a one-line takeaway and the one sentence the diagram cannot carry.9192> **A slow scan blocks an upload worker for the whole call, so a scan slowdown empties the worker pool.**93>94> ```mermaid95> sequenceDiagram96> Client->>Upload: file97> Upload->>Scan: scan (sync, worker blocked)98> Scan->>Metadata: lookup99> Metadata->>Queue: enqueue100> Scan-->>Upload: result (slow)101> Note over Upload: 32 workers, all waiting on Scan102> ```103>104> Scan's latency is inherited by every caller because the upload-to-scan call is synchronous; making that call asynchronous is the change under review.105106**Change handoff note.** A change that removed an upload endpoint, added a rate limit on third-party downloads, and moved files to a new path went through three descriptions. Version one listed merge-request numbers, class names, and four review rounds; the tester could not find what to test, and none of those identifiers survive into the note. Version two was rewritten for the tester and lost the list of what changed. Version three:107108> | Change | Kind | Visible to users |109> | --- | --- | --- |110> | `/upload/legacy` removed | Deletion | Old clients get 404; new path unchanged |111> | Third-party downloads rate-limited (20/min per tenant) | Behaviour | Bursts above the limit wait, not fail |112> | Files served from `/appdownload/` alongside the old path | Path | Both URLs work until the next release |113>114> Design: the service probes the target before uploading and reuses an existing identical file, so a retry of a published file never truncates it. Test first: upload the same package twice and interrupt one; then a burst of 30 downloads; then the old URL. Not a defect: the old URL still serving for one release.115116**Notice.** Two numbers and a date do not need a title, a background section, or next steps:117118> Old login closes Friday 18:00. Signed-in users are unaffected. Anyone not moved to the new login by then cannot sign in on Monday.119120## Agent-facing instruction files121122When the reader is an agent that acts on the file (AGENTS.md, CLAUDE.md, a rules doc), keep only commands, paths, boundaries (what may and may not change), and hard rules stated as their executable part; cut mission, ownership, vision, process asides, and slogans. Delete every line whose removal would not change what the agent does, and title the file with the repository name.
ly87ing