Name the markdown's readers and writers in the audience, and the panel rule
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user