@@ -52,11 +52,22 @@ it should contain the following key components:
52
52
Follow the [tips] (#tips) below to make your explainer as effective as possible.
53
53
54
54
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.
60
71
61
72
# Examples of Good Explainers # {#good-explainers}
62
73
0 commit comments