File tree Expand file tree Collapse file tree 1 file changed +13
-5
lines changed
Expand file tree Collapse file tree 1 file changed +13
-5
lines changed Original file line number Diff line number Diff line change @@ -52,11 +52,19 @@ it should contain the following key components:
5252Follow the [tips] (#tips) below to make your explainer as effective as possible.
5353
5454Once 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
You can’t perform that action at this time.
0 commit comments