Skip to content

Commit d52e626

Browse files
committed
Say that explainer contents should move into specifications.
1 parent 7aeea94 commit d52e626

File tree

1 file changed

+13
-5
lines changed

1 file changed

+13
-5
lines changed

index.bs

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,19 @@ it should contain the following key components:
5252
Follow the [tips](#tips) below to make your explainer as effective as possible.
5353

5454
Once there is a reasonable amount of consensus on the approach and high-level design,
55-
the explainer can be used to guide spec writing,
56-
by serving as a high-level overview of the feature to be specified and the user need it serves.
57-
58-
Once the spec is written and the feature is shipped,
59-
the explainer can then provide a basis for author-facing documentation of the new feature.
55+
use the explainer to guide spec writing.
56+
Start your specification using whatever tool you prefer
57+
(e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)),
58+
and then move (don't copy) sections from your explainer into the specification.
59+
Be sure to leave links from the now-empty explainer sections
60+
to the specification sections that received their content.
61+
62+
As your specification evolves,
63+
be sure to maintain the introduction, use cases, and examples
64+
so that novices can still read them.
65+
This will make it easier for
66+
["wide" reviewers](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review)
67+
to do their reviews.
6068

6169
# Examples of Good Explainers # {#good-explainers}
6270

0 commit comments

Comments
 (0)