Refinements to early design review (#988)

* Refinements to early design review Several things here all together. 1. Change the text a little. 2. Use `{{}}` for stuff that is templatey. The use of `[]` means that we often get design reviews with links called `url`. Leaving slots blank mean that we have less chance of that. 3. Move parenthetical stuff to the footnotes. 4. Link to chrome status, mozilla, and webkit s-p. If this makes sense, I'll do the other template in the same way. * curly * Full review request to match the other I'll now need to port some of these improvements to the other... * Around we go * Round we go More about multi-stakeholder feedback/support * This should do it Improvements to the multi-stakeholder piece to make it consistent with the other. * Some modest proposals Co-authored-by: Jeffrey Yasskin <[email protected]> * You know what, we can be more opinionated on that point too * Go for gold --------- Co-authored-by: Jeffrey Yasskin <[email protected]>
w3ctag · Sep 8, 2024 · 5706573 · 5706573
1 parent acc6378
commit 5706573
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 42 deletions.
diff --git a/.github/ISSUE_TEMPLATE/005-early-design-review.md b/.github/ISSUE_TEMPLATE/005-early-design-review.md
@@ -10,18 +10,23 @@ assignees: ''
 
 こんにちは TAG-さん!
 
-I'm requesting a TAG review of [feature name].
-
-[One paragraph summary of idea, ideally copy-pasted from Explainer introduction]
-
-  - Explainer¹ (minimally containing user needs and example code): [url]
-  - User research: [url to public summary/results of research]
-  - Security and Privacy self-review²: [url]
-  - GitHub repo: [url]
-  - Primary contacts (and their relationship to the specification):
-      - [name] ([github username]), [organization/s] (repeat as necessary, we recommend including group chairs and editors in this list)
-  - Organization/project driving the design: [organization and/or project name]
-  - External status/issue trackers for this feature (publicly visible, e.g. Chrome Status):
+I'm requesting an early TAG design review of {{feature}}.
+
+{{One paragraph summary of idea, ideally copy-pasted from your Explainer.}}
+
+  - Explainer¹:
+  - User research:
+  - Security and Privacy self-review²:
+  - GitHub repo:
+  - Primary contacts:
+      - $name (@-mention), $organization/s, $role in developing specification
+      - {{repeat as necessary, we recommend including group chairs and editors in this list}}
+  - Organization/project driving the design:
+  - Multi-stakeholder feedback³:
+    - Chromium comments:
+    - Mozilla comments: https://github.com/mozilla/standards-positions/issues/NNN
+    - WebKit comments: https://github.com/WebKit/standards-positions/issues/NNN
+    - {{...include feedback/review from developers, implementers, civil society, and others}}
 
 Further details:
 
@@ -34,16 +39,17 @@ Further details:
 
 You should also know that...
 
-[please tell us anything you think is relevant to this review]
+{{Please tell us anything else you think is relevant to this review.}}
 
 ------------------------------------------------------------------------------------
 CAREFULLY READ AND DELETE CONTENT BELOW THIS LINE BEFORE SUBMITTING
 
-Please preview the issue and check that the links work before submitting.
+Use links to content rather than pasting text into this issue. Issues are ephemeral and most of the material we are asking for has long term value.
 
-In particular:
-* if anything links to a URL which requires authentication (e.g. Google document), please make sure anyone with the link can access the document. We would prefer public documents though, since we work in the open.
+Please preview the issue and check that the links work before submitting. Please make sure anyone with the link can access the document. We may refuse to review anything that is not public.
 
-¹ For background, see our [explanation of how to write a good explainer](https://tag.w3.org/explainers/). We recommend the explainer to be in [Markdown](https://github.github.com/gfm/).
+¹ An explainer must address user needs and contain examples of use. See our [explanation of how to write a good explainer](https://tag.w3.org/explainers/).
 
 ² Even for early-stage ideas, a Security and Privacy questionnaire helps us understand potential security and privacy issues and mitigations for your design, and can save us asking redundant questions. See https://www.w3.org/TR/security-privacy-questionnaire/.
+
+³ For your own organization, you can simply state the organization's position instead of linking to it.  This includes items on [Mozilla standards-positions](https://github.com/mozilla/standards-positions), and [WebKit standards-positions](https://github.com/WebKit/standards-positions).  Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.
diff --git a/.github/ISSUE_TEMPLATE/010-specification-review.md b/.github/ISSUE_TEMPLATE/010-specification-review.md
@@ -10,49 +10,51 @@ assignees: ''
 
 こんにちは TAG-さん!
 
-I'm requesting a TAG review of [feature name].
-
-[One paragraph summary of idea, ideally copy-pasted from Explainer introduction]
-
-  - Explainer¹ (minimally containing user needs and example code): [url]
-  - Specification URL: [spec url]
-  - Tests: [wpt folder(s), if available]
-  - User research: [url to public summary/results of research]
-  - Security and Privacy self-review²: [url]
-  - GitHub repo: [url]
-  - Primary contacts (and their relationship to the specification):
-      - [name] ([github username]), [organization/s] (repeat as necessary, we recommend including group chairs and editors in this list)
-  - Organization(s)/project(s) driving the specification: [organization and/or project name]
-  - Key pieces of existing multi-stakeholder (e.g. developers, implementers, civil society) support, review or discussion of this specification
-  - Key pieces of multi-implementer support:
-    - Chromium comments: [url]
+I'm requesting a TAG review of {{feature}}.
+
+{{One paragraph summary of the feature, ideally copy-pasted from your Explainer.}}
+
+  - Explainer¹:
+  - Specification:
+  - WPT Tests:
+  - User research:
+  - Security and Privacy self-review²:
+  - GitHub repo:
+  - Primary contacts:
+      - $name (@-mention), $organization/s, $role in developing specification
+      - {{repeat as necessary, we recommend including group chairs and editors in this list}}
+  - Organization/project driving the specification:
+  - Multi-stakeholder support³:
+    - Chromium comments:
     - Mozilla comments: https://github.com/mozilla/standards-positions/issues/NNN
     - WebKit comments: https://github.com/WebKit/standards-positions/issues/NNN
-    - etc...
-  - External status/issue trackers for this specification (publicly visible, e.g. Chrome Status):
+    - {{...include feedback/review from developers, implementers, civil society, and others}}
+  - Status/issue trackers for implementations⁴:
 
 Further details:
 
   - [ ] I have reviewed the TAG's [Web Platform Design Principles](https://www.w3.org/TR/design-principles/)
-  - Relevant time constraints or deadlines: [please provide]
+  - Relevant time constraints or deadlines:
   - The group where the work on this specification is currently being done:
-  - The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue):
+  - The group where standardization of this work is intended to be done (if different from the current group):
   - Major unresolved issues with or opposition to this specification:
   - This work is being funded by:
 
 You should also know that...
 
-[please tell us anything you think is relevant to this review]
+{{Please tell us anything else you think is relevant to this review.}}
 
 ------------------------------------------------------------------------------------
 CAREFULLY READ AND DELETE CONTENT BELOW THIS LINE BEFORE SUBMITTING
 
-Please preview the issue and check that the links work before submitting.
+Use links to content rather than pasting text into this issue. Issues are ephemeral and most of the material we are asking for has long term value.
 
-In particular, if anything links to a URL which requires authentication (e.g. Google document), please make sure anyone with the link can access the document. We would prefer fully public documents though, since we work in the open.
+Please preview the issue and check that the links work before submitting. Please make sure anyone with the link can access the document. We may refuse to review anything that is not public.
 
-¹ We require an explainer to give the relevant context for the spec review, even if the spec has some background information. For background, see our [explanation of how to write a good explainer](https://tag.w3.org/explainers/). We recommend the explainer to be in [Markdown](https://github.github.com/gfm/).
+¹ We require an explainer to give the relevant context for the spec review, even if the spec has some background information. An explainer must address user needs and contain examples of use.  For more information, see our [explanation of how to write a good explainer](https://tag.w3.org/explainers/).
 
 ² A Security and Privacy questionnaire helps us understand potential security and privacy issues and mitigations for your design, and can save us asking redundant questions. See https://www.w3.org/TR/security-privacy-questionnaire/.
 
-³ For your own organization, you can simply state the organization's position instead of linking to it. Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.
+³ For your own organization, you can simply state the organization's position instead of linking to it.  This includes items on [Mozilla standards-positions](https://github.com/mozilla/standards-positions), and [WebKit standards-positions](https://github.com/WebKit/standards-positions).  Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.
+
+⁴ Include links to [Chrome Status](https://chromestatus.com/), [Mozilla's](https://bugzilla.mozilla.org/), [WebKit's Bugzilla](https://bugs.webkit.org/), and trackers for other implementations if those are known to you.