mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-18 06:05:43 +01:00
Make plain text goal 6.2 and name its readers in the audience
This commit is contained in:
@@ -252,13 +252,13 @@ whatever it costs; the Achieve goals are weighed against each other in the order
|
||||
- Counter-signal: `spec/flavour.md` gains a special case for each such pick.
|
||||
- Why: output fitted case by case is output no reader can predict.
|
||||
1. **Maintain:** A function's name says which markdown it reads or writes.
|
||||
2. **Achieve:** Plain text reads like text written for people reading an email.
|
||||
- Signal: readers shown the candidate texts pick the one the library already writes.
|
||||
- Counter-signal: issues report plain text that reads as markup or runs blocks together.
|
||||
- Why: a spelling that looks tidy to its author can read as markup to its readers, and only their picks and reports show it.
|
||||
7. **Maintain:** Lossy conversion drops form, never content. A link's or an image's title counts as content.
|
||||
8. **Maintain:** Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.
|
||||
9. **Maintain:** Fast, and linear in the document's size as JSON.
|
||||
10. **Achieve:** Plain text reads like text written for people reading an email.
|
||||
- Signal: readers shown the candidate texts pick the one the library already writes.
|
||||
- Counter-signal: issues report plain text that reads as markup or runs blocks together.
|
||||
- Why: a spelling that looks tidy to its author can read as markup to its readers, and only their picks and reports show it.
|
||||
|
||||
## Audience
|
||||
|
||||
@@ -271,15 +271,16 @@ which is free text.
|
||||
refusal arriving before the save rather than after.
|
||||
- **Bot posting content** — turns generated markdown into ADF. Relies on CommonMark being valid
|
||||
input, so nothing upstream has to learn a flavour.
|
||||
- **Export/indexing tool** — converts ADF to markdown or HTML in bulk. Relies on readable output
|
||||
and on every refusal but `engine-limit` being deterministic, so a document that fails fails the
|
||||
same way next run.
|
||||
- **Export/indexing tool** — converts ADF to markdown, HTML or plain text in bulk. Relies on
|
||||
readable output and on every refusal but `engine-limit` being deterministic, so a document that
|
||||
fails fails the same way next run.
|
||||
- **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 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.
|
||||
UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. Some
|
||||
never see markup: they read a document's plain text in an email, a notification or a search hit.
|
||||
|
||||
Contributors, human or agent, who change the source. They rely on each concern having one obvious
|
||||
place, and on CI failing a change that breaks a guarantee.
|
||||
@@ -339,7 +340,7 @@ documentation says, on 2026-10-28.
|
||||
|
||||
## The calls
|
||||
|
||||
Serves [Goals](#goals) 1, 2, 8 and 10. Pure functions, each taking a whole document and returning a
|
||||
Serves [Goals](#goals) 1, 2, 6.2 and 8. Pure functions, each taking a whole document and returning a
|
||||
whole result; no I/O, no configuration. [What each call writes](https://github.com/larvit/adf-codec/blob/main/docs/feature-table.md)
|
||||
sets example documents beside the markdown and HTML writers' output and says whether that output reads back the same.
|
||||
|
||||
|
||||
+1
-1
@@ -1301,7 +1301,7 @@ it wanted the day shown, as `!adf:date[2025-08-25]{timestamp=…}`.
|
||||
|
||||
2026-11-14, a reader panel of 7 (export/indexing, LLM/agent, support agent, viewer/editor, bot,
|
||||
product manager, engineer), then the maintainer; a second panel of 3 (support agent, product
|
||||
manager, export/indexing) for links and task state. Goal 10. Valid while the audience of the text is
|
||||
manager, export/indexing) for links and task state. Goal 6.2. Valid while the audience of the text is
|
||||
people reading an email.
|
||||
|
||||
Each reader of the first panel wrote the text they expected, then picked among six shuffled
|
||||
|
||||
@@ -12,9 +12,8 @@
|
||||
|
||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| 182 | 0.4.0 | | question | **Decide whether the audience names the people reading plain text, and whether goal 10 is a sub-goal of goal 6.** | 1 | 1 | 1 | 1 | 1 | 10 by 3 | 5.6 |
|
||||
| 180 | 0.4.0 | | | **Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.** | 2 | 2 | 2 | 4 | 3 | 3 by 1, 6 by 3 | 4.9 |
|
||||
| 181 | 0.4.0 | | | **Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858.** | 2 | 2 | 2 | 4 | 4 | 3 by 2, 6 by 2 | 3.3 |
|
||||
| 180 | 0.4.0 | | | **Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.** | 2 | 2 | 2 | 4 | 3 | 3 by 1, 6.2 by 3 | 4.8 |
|
||||
| 181 | 0.4.0 | | | **Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858.** | 2 | 2 | 2 | 4 | 4 | 3 by 2, 6.2 by 2 | 3.3 |
|
||||
| 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 3.2 |
|
||||
| 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 |
|
||||
| 136 | 0.4.0 | | | **Write underline, text and background colours, subscript, superscript, alignment and indentation as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 |
|
||||
@@ -51,17 +50,6 @@
|
||||
|
||||
## Details
|
||||
|
||||
### 182. Decide whether the audience names the people reading plain text, and whether goal 10 is a sub-goal of goal 6.
|
||||
|
||||
`## Audience` lists no one who sends notifications or emails, and goal 10 reads like a narrower case of
|
||||
goal 6 (what output the audience expects), with the same signal. Two choices are the maintainer's:
|
||||
|
||||
- Add the readers of an email, a notification and a search hit to `## Audience`, so goal 10's
|
||||
readers are named there.
|
||||
- Keep goal 10 as it is, or make it goal 6.2 and cite 6.2 in the Moves of items 180 and 181.
|
||||
|
||||
Raised by the product-owner and prose reviews of the chunk that shipped `adfToPlainText`.
|
||||
|
||||
### 180. Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.
|
||||
|
||||
A reader panel picks the cell separator, and what a header row, a merged cell and a block nested in
|
||||
|
||||
Reference in New Issue
Block a user