Skip to content

Commit 6e6adaf

Browse files
jyasskintorgoalice
authored
Describe how explainer contents should move into specifications. (#25)
Co-authored-by: Daniel Appelquist <[email protected]> Co-authored-by: Alice <[email protected]>
1 parent 7aeea94 commit 6e6adaf

File tree

1 file changed

+16
-5
lines changed

1 file changed

+16
-5
lines changed

index.bs

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,22 @@ 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+
You can move or copy sections of your explainer directly into your specification
57+
or a [Group Note](https://www.w3.org/policies/process/#note-track)
58+
mentioned under the same [umbrella specification](https://www.w3.org/TR/spec-variability/#umbrella).
59+
Make sure that the explainer remains useful and accurate over time.
60+
If you move sections out of it,
61+
replace them with links to the relevant part of the spec.
62+
If you keep redundant text in the explainer,
63+
remember to update it as the specification changes.
64+
65+
As your specification and explainer evolve,
66+
be sure to maintain their introductions, use cases, and examples
67+
so that novices can still read them.
68+
This will make it easier for
69+
["wide" reviewers](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review)
70+
to do their reviews.
6071

6172
# Examples of Good Explainers # {#good-explainers}
6273

0 commit comments

Comments
 (0)