From 8d657a6a7a2beab405ceaac3a70818a0a59256b7 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 14 Nov 2026 16:32:03 +0100 Subject: [PATCH] Make plain text goal 6.2 and name its readers in the audience --- README.md | 19 ++++++++++--------- docs/decisions.md | 2 +- todo.md | 16 ++-------------- 3 files changed, 13 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index c263c29..2734355 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/decisions.md b/docs/decisions.md index 3c6e48b..abbe383 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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 diff --git a/todo.md b/todo.md index 0277194..9dddc09 100644 --- a/todo.md +++ b/todo.md @@ -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