Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -271,16 +271,20 @@ 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.

Also behind them, the people who read a document's plain text as they read an email, whether it
arrives in an email, a notification or a search hit. They see no markup, and rely on text that
reads as written for them.

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.

Expand Down Expand Up @@ -339,7 +343,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.

Expand Down
2 changes: 1 addition & 1 deletion docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 2 additions & 14 deletions todo.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down