Name the markdown's readers and writers in the audience, and the panel rule

This commit is contained in:
2026-10-03 12:03:20 +02:00
parent 6f689a51b0
commit bfc4b2ce00
2 changed files with 9 additions and 1 deletions
+5 -1
View File
@@ -162,12 +162,16 @@ nearest text, a candidate entry in that file's voice, and the instance it yields
keeps collecting instances is wrong: rewrite it.
Which output the audience expects — README goal 5 — is settled by a reader panel rather than
asked: three fresh-context readers, one per README persona the conversion serves, each given only
asked: three fresh-context readers, one per README persona the question serves, each given only
`## Audience` and the input, writing what they expect before picking among outputs the goals
allow, rendered, shuffled, with no rationale and nothing saying what is implemented. Three agreeing
settle it; otherwise four more read, five of seven settle it, and less is a missing goal, asked.
The verdict lands in `docs/decisions.md`.
Every new or changed markdown or HTML spelling goes to such a panel, seated by the people who read
and write that format (README `## Audience`); a question about what an app relies on seats the
developer personas.
### Stated numbers
A stated number — 500 levels, the branch floor — is kept; a chunk that cannot keep it asks, naming
+4
View File
@@ -52,6 +52,10 @@ which is free text.
- **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back.
Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit.
Behind those apps, the people who read and write the markdown, and later the HTML: product
managers, engineers and support agents working in Atlassian products through a plugin or another
UI. They know markdown and not ADF, and rely on every spelling saying what it means to them.
## The shape
```sh