Skip to content

Rewrite validation-codes.md at the API-consumer altitude#1106

Merged
alistair3149 merged 2 commits into
masterfrom
docs/validation-codes-text-pass
Jul 20, 2026
Merged

Rewrite validation-codes.md at the API-consumer altitude#1106
alistair3149 merged 2 commits into
masterfrom
docs/validation-codes-text-pass

Conversation

@JeroenDeDauw

Copy link
Copy Markdown
Member

Follows-up to #1082

A full text pass over the validation-codes reference for its actual reader: an API consumer deciding
what a code means, whether their write fails, and what to do next. Everything that derived or
justified the contract instead of stating it is gone:

  • Emitter-class names and validator-loop narration (SubjectValidator, StatementListBuilder, ...).
    Entries now use schema type names (text, dateTime) instead of PHP class names.
  • The relation-target resolution anatomy (revision slots, subject-to-page index, graph staleness,
    Imported revisions do not update the graph projection #1022): read consistency is a system-wide property homed in operations/maintenance.md, not
    something to restate per validation code.
  • Design-rationale asides and roadmap notes ("would be redundant noise", the 404-asymmetry
    reconciliation note).
  • The "Known limitations" inventory of which class performs which check — it duplicated the entries.
  • RedHerb's invalid-color entry: extension codes belong to the extension's docs (step 5 of the
    plugin-author section now says exactly that); RedHerb stays as the worked-example pointer.

Blocking semantics now live in one "Blocking and enforcement" section instead of an intro bullet
plus per-entry restatements; only the three non-blocking codes carry a marker, and per-entry
propertyName/valuePartIndex lines that restated defaults are gone.

Completeness fixes found on the way: min-length, max-length, invalid-date, and
unregistered-type are emitted but were undocumented (the last was even referenced by name), and
min-value/max-value are also emitted by date properties, which the emitter list omitted.

AI-authored — Claude Code, Fable 5 (max); text-review pass directed by @JeroenDeDauw, spec calibrated over three rounds of in-session discussion of #1082's doc text, the rewrite itself unredirected; not yet human-reviewed; every stated behavior verified against the validator source, doc links checked against their targets, docs-only change.

Follows-up to #1082

A full text pass over the validation-codes reference for its actual reader: an API consumer deciding
what a code means, whether their write fails, and what to do next. Everything that derived or
justified the contract instead of stating it is gone:

- Emitter-class names and validator-loop narration (SubjectValidator, StatementListBuilder, ...).
  Entries now use schema type names (`text`, `dateTime`) instead of PHP class names.
- The relation-target resolution anatomy (revision slots, subject-to-page index, graph staleness,
  #1022): read consistency is a system-wide property homed in operations/maintenance.md, not
  something to restate per validation code.
- Design-rationale asides and roadmap notes ("would be redundant noise", the 404-asymmetry
  reconciliation note).
- The "Known limitations" inventory of which class performs which check — it duplicated the entries.
- RedHerb's `invalid-color` entry: extension codes belong to the extension's docs (step 5 of the
  plugin-author section now says exactly that); RedHerb stays as the worked-example pointer.

Blocking semantics now live in one "Blocking and enforcement" section instead of an intro bullet
plus per-entry restatements; only the three non-blocking codes carry a marker, and per-entry
propertyName/valuePartIndex lines that restated defaults are gone.

Completeness fixes found on the way: `min-length`, `max-length`, `invalid-date`, and
`unregistered-type` are emitted but were undocumented (the last was even referenced by name), and
`min-value`/`max-value` are also emitted by `date` properties, which the emitter list omitted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@JeroenDeDauw
JeroenDeDauw marked this pull request as ready for review July 20, 2026 20:10
Context about which surface typically produces the code, not part of the
contract; resolved toward this pass's cut-by-default policy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alistair3149
alistair3149 merged commit 3ea7a9f into master Jul 20, 2026
6 checks passed
@alistair3149
alistair3149 deleted the docs/validation-codes-text-pass branch July 20, 2026 20:34
JeroenDeDauw added a commit that referenced this pull request Jul 20, 2026
Follows-up to #1106

#1106 rewrote `docs/api/validation-codes.md` to its reader's altitude and cut everything that derived, justified,
or narrated mechanism rather than stating the contract. This adds `docs/writing.md`, which codifies that standard
so the next page holds to it by default.

The page states, in under 45 lines: a rule block (fix the reader, their decision, and a length budget before
writing; state contracts, don't narrate mechanism; one home per fact; no history of the text's own production;
improving a page doesn't lengthen it), a genre table assigning each `docs/` area its reader and register, and a
short list of banned phrasings.

Placement: `docs/writing.md` at the docs root, no frontmatter. The site nav is curated, not built from every file
(`planning/` is excluded per `docs/README.md`), and published leaves carry the `title`/`order` frontmatter this
page omits, so it stays out of the product navigation. The docs-deploy workflow only triggers the site build; the
nav lives in the website project.

Genre mapping: there is no `concepts/` or `reference/` directory, so those genres map to the docs-root concept
pages and to `authoring/` + `rdf/` + `examples/`. Every existing `docs/` subdirectory is covered by one row.

Considered, omitted: a standalone row for `examples/` (folded into the reference genre); `title`/`order`
frontmatter (would list it in the nav); a cross-link from `docs/README.md` (this change adds one file only); a
fuller description of the deploy pipeline (out of the page's genre). No repo-root `CLAUDE.md`/`AGENTS.md` exists,
so no AI-context pointer was added.

> <sub>AI-authored — Claude Code, `Opus 4.8 (max)`; executed from a fixed skeleton and genre assignments specified by a Fable 5 session directed by @JeroenDeDauw; not yet human-reviewed; placement verified against the docs-site build config, links checked, docs-only change.</sub>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants