From ce72ef72944d1b752b6c010c3a59667428d44b95 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Tue, 10 Jun 2025 04:09:48 +0000 Subject: [PATCH 1/6] Say that explainer contents should move into specifications. --- index.bs | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 1450641..576a95e 100644 --- a/index.bs +++ b/index.bs @@ -52,11 +52,19 @@ it should contain the following key components: Follow the [tips](#tips) below to make your explainer as effective as possible. Once there is a reasonable amount of consensus on the approach and high-level design, -the explainer can be used to guide spec writing, -by serving as a high-level overview of the feature to be specified and the user need it serves. - -Once the spec is written and the feature is shipped, -the explainer can then provide a basis for author-facing documentation of the new feature. +use the explainer to guide spec writing. +Start your specification using whatever tool you prefer +(e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)), +and then move (don't copy) sections from your explainer into the specification. +Be sure to leave links from the now-empty explainer sections +to the specification sections that received their content. + +As your specification evolves, +be sure to maintain the introduction, use cases, and examples +so that novices can still read them. +This will make it easier for +["wide" reviewers](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review) +to do their reviews. # Examples of Good Explainers # {#good-explainers} From 206ebe933b58476ae1a6632e4cae76bf37977809 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Tue, 17 Jun 2025 11:27:11 -0700 Subject: [PATCH 2/6] Give authors a choice whether to move their explainer into their spec. Co-authored-by: Daniel Appelquist --- index.bs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 576a95e..bcebb23 100644 --- a/index.bs +++ b/index.bs @@ -54,9 +54,9 @@ Follow the [tips](#tips) below to make your explainer as effective as possible. Once there is a reasonable amount of consensus on the approach and high-level design, use the explainer to guide spec writing. Start your specification using whatever tool you prefer -(e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)), -and then move (don't copy) sections from your explainer into the specification. -Be sure to leave links from the now-empty explainer sections +(e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)). +You may want to move (not copy) sections from your explainer into the specification as you write it. +If you do, be sure to leave links from the now-empty explainer sections to the specification sections that received their content. As your specification evolves, From 8776eb4af99697754d3a2601cbedd3b9f5fce9cd Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 25 Jun 2025 09:42:34 -0700 Subject: [PATCH 3/6] Take Alice's wording. Co-authored-by: Alice <95208+alice@users.noreply.github.com> --- index.bs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index bcebb23..cd25d2e 100644 --- a/index.bs +++ b/index.bs @@ -55,9 +55,11 @@ Once there is a reasonable amount of consensus on the approach and high-level de use the explainer to guide spec writing. Start your specification using whatever tool you prefer (e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)). -You may want to move (not copy) sections from your explainer into the specification as you write it. -If you do, be sure to leave links from the now-empty explainer sections -to the specification sections that received their content. +The parts of your explainer which document how developers should use the new API +can be copied or moved into the specification. +You should make sure the explainer remains useful either way: +you can save some effort by replacing the moved sections with links into the relevant part of the spec, +or you may prefer to edit the explainer as necessary to ensure it remains consistent. As your specification evolves, be sure to maintain the introduction, use cases, and examples From e86cd590890df53a83c645c7e17ec455c4b11071 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 25 Jun 2025 16:44:17 +0000 Subject: [PATCH 4/6] Remove the mention of spec-writing tools. --- index.bs | 2 -- 1 file changed, 2 deletions(-) diff --git a/index.bs b/index.bs index cd25d2e..9c4b463 100644 --- a/index.bs +++ b/index.bs @@ -53,8 +53,6 @@ Follow the [tips](#tips) below to make your explainer as effective as possible. Once there is a reasonable amount of consensus on the approach and high-level design, use the explainer to guide spec writing. -Start your specification using whatever tool you prefer -(e.g. [Bikeshed](https://speced.github.io/bikeshed/) or [Respec](https://respec.org/)). The parts of your explainer which document how developers should use the new API can be copied or moved into the specification. You should make sure the explainer remains useful either way: From f0bc098a3ba3e9ac43aa8569fba1a2eea8e4038e Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 25 Jun 2025 10:29:46 -0700 Subject: [PATCH 5/6] Tweak the "if you move/copy" explanation. --- index.bs | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 9c4b463..32a0a0d 100644 --- a/index.bs +++ b/index.bs @@ -53,11 +53,14 @@ Follow the [tips](#tips) below to make your explainer as effective as possible. Once there is a reasonable amount of consensus on the approach and high-level design, use the explainer to guide spec writing. -The parts of your explainer which document how developers should use the new API -can be copied or moved into the specification. -You should make sure the explainer remains useful either way: -you can save some effort by replacing the moved sections with links into the relevant part of the spec, -or you may prefer to edit the explainer as necessary to ensure it remains consistent. +You can move or copy sections of your explainer directly into your specification +or a [Group Note](https://www.w3.org/policies/process/#note-track) +mentioned under the same [umbrella specification](https://www.w3.org/TR/spec-variability/#umbrella). +Make sure that the explainer remains useful and accurate over time. +If you move sections out of it, +replace them with links to the relevant part of the spec. +If you keep redundant text in the explainer, +remember to update it as the specification changes. As your specification evolves, be sure to maintain the introduction, use cases, and examples From 9cd953de9db0dccbf40cfbeb3231bf60f5278991 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Tue, 1 Jul 2025 23:28:06 -0700 Subject: [PATCH 6/6] Clarify which introductions, etc should be maintained. --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 32a0a0d..9c85a4b 100644 --- a/index.bs +++ b/index.bs @@ -62,8 +62,8 @@ replace them with links to the relevant part of the spec. If you keep redundant text in the explainer, remember to update it as the specification changes. -As your specification evolves, -be sure to maintain the introduction, use cases, and examples +As your specification and explainer evolve, +be sure to maintain their introductions, use cases, and examples so that novices can still read them. This will make it easier for ["wide" reviewers](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review)