Skip to content

docs(Guide): add a why-spec page, and stop three places underselling it - #2217

Merged
DerManoMann merged 1 commit into
zircote:masterfrom
DerManoMann:docs/why-spec
Sep 26, 2026
Merged

DerManoMann merged 1 commit into
zircote:masterfrom
DerManoMann:docs/why-spec

Conversation

@DerManoMann

Copy link
Copy Markdown
Collaborator

Overview

The spec pipeline has a guide, a reference, an extension-points page and a tab on the homepage
snippet. It has nowhere that answers why anyone would move to it.

Three of the places a reader forms a first impression argue against it by accident. The
homepage info box's operative sentence is "the mode needs to be set to spec" — a chore,
above the snippet, before any reason to care. The modes table offers spec as "Best for: New
projects"
, which tells every existing project not to look. The README bullet is a list of
internals ending in "version-aware compilers".

The new page leads with the thing classic attributes cannot do at all: spec attributes are
ordinary objects, so a document can be built from values and compiled with nothing to scan —
which is what an integration whose API surface is computed rather than declared needs. The
snippet showing it is executed by the test suite against a committed expectation, so the page
cannot drift from what the library does. The other sections are the mistakes the pipeline
reports instead of absorbing, output versions as compiler targets, and what a Specification
already exposes.

The modes table loses its "Best for" row rather than getting a better answer: the row above it
already says what each mode reads, which is the axis that actually decides the question.

ROADMAP.md also stops predicting on a named third party's behalf. The bridge has nothing to
scan for when an integration builds annotation objects directly rather than scanning for them,
so the v7 exception is now stated as that mechanism — which is the reason, and stays true of
anything shaped that way.

Changes

  • Add docs/guide/why-spec.md, with a sidebar entry above "Processing Modes"
  • Add docs/snippets/guide/why-spec/value_objects.php and its expected output, executed by a
    new WhySpecSnippetTest
  • Rewrite the homepage spec info box to say what the attributes are and link the new page
  • Drop the "Best for" row from the modes table
  • Replace the README's spec bullet with a reason and a link
  • State the v7 bridge exception in ROADMAP.md as a mechanism rather than a named project

The spec pipeline has a guide, a reference, an extension-points page and a
homepage tab, and nowhere that answers why anyone would move to it. Three of the
places a reader forms an impression argued against it by accident: the homepage
info box read as a chore ("the mode needs to be set to spec"), the modes table
offered spec as "best for: new projects", and the README bullet listed internals.

The new page leads with the one thing classic attributes cannot do at all —
building a document from values with nothing to scan — and the snippet it shows
is executed by the suite, so the page cannot drift from what the library does.
The other three sections are validation, version targets and what a
Specification already exposes to an integration.

The modes table loses its "best for" row rather than getting a better answer:
the row above it already says what each mode reads, which is the axis that
decides the question.

ROADMAP.md stops predicting on a named third party's behalf. The bridge has
nothing to scan for when an integration builds annotation objects directly, so
the exception is stated as that mechanism, which is both the reason and true of
anything shaped that way.
@DerManoMann
DerManoMann merged commit f998f7e into zircote:master Sep 26, 2026
19 checks passed
@DerManoMann
DerManoMann deleted the docs/why-spec branch September 26, 2026 07:11
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.

1 participant