docs(Guide): add a why-spec page, and stop three places underselling it - #2217
Merged
Merged
Conversation
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.
6 of 10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
Specificationalready 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.mdalso stops predicting on a named third party's behalf. The bridge has nothing toscan 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
docs/guide/why-spec.md, with a sidebar entry above "Processing Modes"docs/snippets/guide/why-spec/value_objects.phpand its expected output, executed by anew
WhySpecSnippetTestspecinfo box to say what the attributes are and link the new pageROADMAP.mdas a mechanism rather than a named project