Make goal 12 great documentation, state how the README meets it, and plan the README's reorganisation for 0.2.0

2026-10-14 22:50:30 +02:00
parent 5b1169f9a5
commit 79dafa38f0
2 changed files with 38 additions and 11 deletions
@@ -1117,10 +1117,7 @@ Where the project is heading; the sections before Audience document what ships t
    1. In the library, the caller supplies everything that can change the output: data,
       seed and date.
 11. **No unnecessary runtime dependencies** — use standard library by default.
-12. **The docs are a map of the template language.**
+12. **Great documentation.**
    1. Every feature has its own heading.
    2. Every example runs as a test and shows its output.
    3. Each rule is stated in one place.
 13. **It is fast enough that you never notice it with the shipped data.**
    1. A render's cost grows only with the data it reaches.
 14. **Strongly prioritize data sourced from good online sources**
@@ -1313,6 +1310,21 @@ replaces what it uploaded before. For a tag older than the latest release it lea
 tap, the bucket, the image's `latest` tags and the repositories alone, since each holds one
 version.
 ### Documentation
 How the README serves goal 12:
 - The top shows the CLI and the library side by side, each a short quickstart rendering
  the same value.
 - A table of the shipped data follows: every path, an example value, and what makes it
  valid or where it comes from.
 - Recipes show common tasks end to end.
 - Every feature has its own heading, and the docs are a map of the template language.
 - Every example runs as a test and shows its output.
 - Each rule is stated in one place.
 - Edge cases and a category's caveats sit in the reference sections, below what a first
  reader needs.
 ## License
 MIT — see [LICENSE](LICENSE). Forked from [github.com/Timewave-AB/fakes](https://github.com/Timewave-AB/fakes).
@@ -6,7 +6,7 @@
 `Bar = 9`
-`Next ID = 258`
+`Next ID = 262`
 | Goal | W |
 |---|---|
@@ -52,9 +52,6 @@
 | 10.1 | 0.55 |
 | 11 | 0.50 |
 | 12 | 0.45 |
 | 12.1 | 0.45 |
 | 12.2 | 0.45 |
 | 12.3 | 0.45 |
 | 13 | 0.40 |
 | 13.1 | 0.40 |
 | 14 | 0.35 |
@@ -102,6 +99,7 @@
 | 177 | 0.2.0 | decision | **Run the nine-seat comprehension panel and the scoring run again once item 107 has moved the engine, and file what the panel names.** | 1 | 3 | 2 | 3 | 9 | 3 | 20.4 |
 | 244 | 0.2.0 |  | **Draw `en_US.company`'s suffixes and name patterns from SEC company names, and add `en_US.naics`, a table of NAICS 2022 codes.** | 2 | 4 | 3 | 6 | 6 | 2.1 | 20.4 |
 | 247 | 0.2.0 |  | **Add `en_US.licenseplate`, drawn per state from that state's pattern.** | 2 | 4 | 3 | 6 | 6 | 2, 4 | 20.4 |
 | 259 | 0.2.0 |  | **Follow the quickstarts with a table of every shipped path, its example value and what makes it valid or where it comes from, generated from the data and checked by a test.** | 2 | 4 | 4 | 8 | 8 | 12, 15 | 20.2 |
 | 196 | 0.2.0 | decision | **Name, in the error for a reference nothing loaded provides, the module the reader's manifest reads by default that would provide it, or say none does.** | 3 | 4 | 6 | 6 | 8 | 6.2, 9.2 | 20.0 |
 | 91 | 0.2.0 |  | **Accept a path through a name as a `calc` operand, so `{/misc.coordinate as c}{c}: {calc(c.lat * 60)}` computes from the coordinate `{c}` prints.** | 3 | 4 | 7 | 6 | 7 | 4.1, 5.3 | 19.9 |
 | 223 | 0.2.0 |  | **Let a column draw a key from another record's rows, so an order's `user_id` names a user the same run wrote.** | 4 | 6 | 9 | 7 | 6 | 2, 4.1 | 19.9 |
@@ -111,12 +109,14 @@
 | 220 | 0.2.0 |  | **Suggest the nearest name where a path segment names nothing: `no entry "adress"; did you mean "address"?`.** | 1 | 3 | 3 | 6 | 6 | 6 | 19.2 |
 | 222 | 0.2.0 |  | **Write `--format sql` and `SQLInsert` rows as multi-row INSERTs, so a bulk fixture loads fast.** | 2 | 3 | 3 | 6 | 5 | 1 | 19.2 |
 | 41 | 0.2.0 | decision | **Key every table by one key column, as the decision "A table selects by one key column, a code, never a free-form name" states.** | 6 | 7 | 5 | 7 | 8 | 5.5 | 19.1 |
 | 258 | 0.2.0 |  | **Open the README with a CLI quickstart and a Go quickstart side by side, rendering the same value.** | 1 | 1 | 2 | 7 | 7 | 12 | 19.1 |
 | 52 | 0.2.0 |  | **Name the file a link error comes from beside its category path, `sub.x (/d/a/sub/x.json): …`.** | 1 | 2 | 2 | 5 | 7 | 6 | 19.0 |
 | 117 | 0.2.0 |  | **List the fields of what a path has reached when its next segment names one that is not there: `{/word as a}{a.zz}` reports `no field "zz"; word has w`.** | 1 | 2 | 3 | 5 | 7 | 6 | 19.0 |
 | 28 | 0.2.0 | decision | **Accept a middle name, and draw a `personnummer` whose sex matches a sex selected through a named pick.** | 4 | 4 | 6 | 6 | 7 | 4.1 | 18.9 |
 | 24 | 0.2.0 | defect | **Stop `misc.territory[EH].tld` rendering `.eh`, the one shipped TLD `misc.tld` does not hold.** | 1 | 1 | 1 | 4 | 7 | 4 | 18.6 |
 | 239 | 0.2.0 |  | **Add `sv_SE.month` and `sv_SE.weekday` names from CLDR, and `sv_SE.holiday` from lag 1989:253.** | 2 | 3 | 2 | 5 | 6 | 2.1 | 18.6 |
 | 250 | 0.2.0 |  | **Add `en_US.month` and `en_US.weekday` names from CLDR, and `en_US.holiday`, the federal holidays.** | 2 | 3 | 2 | 5 | 6 | 2.1 | 18.6 |
 | 260 | 0.2.0 |  | **Add a Recipes section: seed a PostgreSQL table, fill a struct in a Go test, make a column unique, and build parent and child records in Go.** | 1 | 3 | 3 | 7 | 7 | 12 | 18.6 |
 | 178 | 0.2.0 |  | **Plan with the systems architect which `internal/` packages the engine splits into, by area, and how each type stops being written by more than one stage, then file the moves as items.** | 1 | 3 | 9 | 2 | 9 | 3, 3.2 | 18.4 |
 | 246 | 0.2.0 |  | **Add `en_US.bankaccount`, an account number of at most 17 characters, the width of a Nacha ACH entry's account field.** | 1 | 2 | 2 | 5 | 5 | 2.1 | 18.0 |
 | 193 | 0.2.0 | decision | **Move the largest shipped packages into nested Go modules that keep their import paths, once `TestShippedDataStaysUnder100MiB` fails.** | 6 | 6 | 6 | 6 | 7 | 2.2, 2 | 17.8 |
@@ -159,7 +159,7 @@
 | 46 | 0.2.0 |  | **Report the same error every load for a table with two bad options.** | 2 | 2 | 2 | 3 | 7 | 6, 10 | 14.0 |
 | 110 | 0.2.0 |  | **Refuse an empty segment in a path `Fake` and `FakeRecord` take, as a reference does: `sv_SE.person.` reports `path has an empty segment`.** | 1 | 1 | 2 | 3 | 6 | 6 | 13.8 |
 | 158 | 0.2.0 |  | **Drop a UTF-8 byte order mark that starts stdin, and say in the README how to stop PowerShell 5.1 sending `Göteborg` as `G?teborg`.** | 2 | 2 | 2 | 4 | 5 | 7.2, 5.1 | 13.5 |
-| 226 | 0.2.0 |  | **Show in the README how to make a column unique, such as an email's local part carrying `{seq()}`.** | 1 | 2 | 1 | 4 | 4 | 4 | 13.3 |
+| 261 | 0.2.0 |  | **Move the README's edge cases and each category's caveats into the reference sections, below what a first reader needs.** | 2 | 4 | 4 | 5 | 7 | 12 | 13.3 |
 | 166 | 0.2.0 |  | **Let a key or name cell hold a bracket, a brace, a double quote or a pipe, so the table loads, its row draws at random, and only a selector cannot reach it.** | 2 | 2 | 4 | 3 | 6 | 5.7 | 13.1 |
 | 171 | 0.2.0 |  | **Handle a template that only reads one record column in one place, so `checkColumns`, `itemDatatype`, `proveColumnItem` and `renderLeaf` no longer each special-case `readsColumn`.** | 3 | 3 | 7 | 2 | 7 | 3, 3.2 | 12.8 |
 | 252 | 0.2.0 |  | **Publish `fejkdata-bin` to the AUR from the Packages workflow, so Arch installs with `yay -S fejkdata-bin`.** | 1 | 1 | 1 | 3 | 4 | 1.1 | 12.8 |
@@ -194,10 +194,9 @@
 | 11 | 0.3.0 |  | **Test that every `geo` tree holds the five table names and the `address` columns that port across countries.** | 1 | 2 | 2 | 3 | 5 | 4 | 13.0 |
 | 35 | 0.3.0 |  | **Add `{base64url(n)}` for JWT shapes.** | 1 | 2 | 3 | 4 | 5 | 8 | 13.0 |
 | 40 | 0.3.0 |  | **Parse `defaultTable`'s path with the library's grammar.** | 2 | 2 | 3 | 3 | 5 | 3.2 | 12.5 |
 | 21 | 0.3.0 |  | **List `title` in both locales, and `sv_SE`'s `birth-number`, in the README's Data list of what each locale carries.** | 1 | 1 | 1 | 4 | 6 | 12 | 12.2 |
 | 86 | 0.3.0 |  | **Read both `en_US.phone` formats' area codes from one category, as their exchange reads `en_US.phone-exchange`.** | 1 | 2 | 2 | 2 | 5 | 3.2 | 11.5 |
 | 23 | 0.3.0 |  | **Give every other shipped category that could reach something real a path that never does.** | 3 | 6 | 4 | 6 | 7 | 16 | 11.0 |
-| 75 | 0.3.0 |  | **Run every README `sh`, `go` and `text` example as a test, and compare each "Renders" line to a seeded render.** | 2 | 6 | 5 | 4 | 7 | 12.2 | 10.8 |
+| 75 | 0.3.0 |  | **Run every README `sh`, `go` and `text` example as a test, and compare each "Renders" line to a seeded render.** | 2 | 6 | 5 | 4 | 7 | 12 | 10.8 |
 | 33 | 0.3.0 |  | **Group `data/misc` into folders where a group name makes a path easier to guess.** | 4 | 5 | 4 | 4 | 5 | 5 | 10.8 |
 | 72 | 0.3.0 | principle | **Fail the merge gate when test coverage falls below the last recorded figure.** | 2 | 3 | 3 | 2 | 5 | 3 | 10.2 |
 | 30 | 0.3.0 |  | **Draw `email.local` from `username`, so the two share one handle list.** | 2 | 2 | 2 | 3 | 5 | 8 | 10.0 |
@@ -408,6 +407,10 @@ NAICS 2022 is public domain; SEC's `company_tickers.json` is free to reuse. [Sou
 No open list of state patterns exists: write each state's pattern by hand and check it against that state's DMV. Wikipedia's list (CC BY-SA) and openalpr's (AGPL) may be read, never copied. [Source research](docs/research/research-sources-world.md).
 ### 259. Follow the quickstarts with a table of every shipped path, its example value and what makes it valid or where it comes from, generated from the data and checked by a test.
 "What can I get?" is a reader's first question, and today the answer is one sentence in the Data section, about 440 lines down. Group the rows by `sv_SE`, `en_US`, `misc` and `geo`. Generate them from `List` and one seeded render per path, and have `readme_test.go` fail when the table drifts. The Data section keeps the sources and the linked-table detail. Replaces item 21, so `title` and `birth-number` are listed with the rest.
 ### 196. Name, in the error for a reference nothing loaded provides, the module the reader's manifest reads by default that would provide it, or say none does.
 Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0", and ends the locale-address decision's conflict with goal 6.2. Carved out of item 182 on 2026-10-11, after six rounds of the comprehension panel ruled each attempt worse. Tried and ruled worse: a module list carried per category from each source's manifest (two routes, `walked` and `indexed`); the union of every manifest's list on the `Generator`, noted at four entry points; and the same noted inside `loadReached`, its list threaded through `loadInline` and `structCompile`. Each named every module read, even loaded ones, until the list held namespaces and the note named only those nothing in the tree provides, which the product-owner and goals reviewers accepted. A shipped locale's `Modules()` already carries its places, so this serves a bare `FS` beside a stand-in, a `--data-path` folder and anyone else's module; the error names the module and points to `Modules()`, as the 2026-10-11 bench asked. Bench the manifest key and the note's wording with the data author, since entries changed from import paths to namespaces after the 2026-10-11 bench.
@@ -441,6 +444,10 @@ The maintainer ruled so on 2026-10-09: a name is a lexical closure, as the decis
 - Drop `key` from `last-name` and `sv_SE.title`, and re-pin `testdata/shipped_shape.txt`.
 - Leave no selection by name in README.md, CHANGELOG.md, docs/ or `--help`.
 ### 258. Open the README with a CLI quickstart and a Go quickstart side by side, rendering the same value.
 The opening line says "a Go library and a CLI", but its example is CLI-only, and the Library section starts after about 150 lines of CLI detail. A Go reader learns late that the library composes with code: a loop per parent, a random count, a shuffle for exact counts. README → Development → Documentation states the layout.
 ### 52. Name the file a link error comes from beside its category path, `sub.x (/d/a/sub/x.json): …`.
 With several `--data-path` layers the author has to work out which directory won, while a parse error on the same file names it.
@@ -465,6 +472,10 @@ CLDR is under the Unicode licence; the law is facts. [Source research](docs/rese
 CLDR is under the Unicode licence. [Source research](docs/research/research-sources-world.md). The federal holidays are listed in 5 U.S.C. 6103, which no research file covers yet.
 ### 260. Add a Recipes section: seed a PostgreSQL table, fill a struct in a Go test, make a column unique, and build parent and child records in Go.
 Each recipe runs as a test. The unique column carries `{seq()}`, as in an email's local part (it replaces item 226). The parent and child recipe compiles one template per parent with `NewTemplate`, draws the child count in Go, and marshals with `encoding/json`, as the 2026-10-14 Jira seeding experiment needed.
 ### 178. Plan with the systems architect which `internal/` packages the engine splits into, by area, and how each type stops being written by more than one stage, then file the moves as items.
 The maintainer chose on 2026-10-09 to regroup the engine into packages in 0.2.0, untangled first, over naming the root files by area. What the panels of 2026-10-09 on b9d1af6 found:
@@ -612,6 +623,10 @@ Today `Fake("sv_SE.person.")` reports `no field ""`, while `{/sv_SE.person.}` re
 A file a Windows editor saves with a BOM prints an invisible U+FEFF first, and a JSON template with one is read as a format string. PowerShell 5.1 encodes what it pipes to a program by `$OutputEncoding`, ASCII by default. The maintainer chose 0.2.0 on 2026-10-07.
 ### 261. Move the README's edge cases and each category's caveats into the reference sections, below what a first reader needs.
 Examples: the bytes stdin renders, MySQL's `ANSI_QUOTES`, CSV rows spanning lines, `misc.timezone`'s standard offset against DST, and a Swedish street that may sit under a neighbouring postort. A category's caveat may instead be a note in item 259's table. Each rule still sits in one place.
 ### 166. Let a key or name cell hold a bracket, a brace, a double quote or a pipe, so the table loads, its row draws at random, and only a selector cannot reach it.
 The maintainer ruled so on 2026-10-09. Today `checkSelectorCells` in `internal/rows` refuses the whole table. Afterwards a path naming such a key fails with an error naming the character a selector cannot spell, and the README says a row whose name holds such a character is still selected by its key.