Revision to explainer explainer

explainers/index.md

@@ -10,30 +10,38 @@ title: Explainers
 - [Explainer
   template](https://github.com/w3ctag/tag.w3.org/blob/main/explainers/template.md)
 
-## Introduction
+# Writing Effective Explainers for W3C TAG Review
 
-Your explainer is a living document that describes the current state of your proposed web platform feature, or collection of features.
+Introduction:
+Your explainer is a living document that describes the current state of your proposed web platform feature or collection of features. It serves as a means to communicate and facilitate multi-stakeholder discussions and consensus-building.
 
-In the early phases of design, this may be as simple as a collection of goals and a sketch of one possible solution.
+Key Components of an Explainer:
 
-As your work progresses, the explainer can help facilitate multi-stakeholder discussion and consensus-building by making clear:
+1. User-Facing Problem:
+Clearly articulate the problem that your proposed feature aims to solve from the user's perspective.
 
-- the user-facing problem which needs to be solved;
-- the proposed approach to solving the problem;
-- the way the proposed solution may be used in practice to address the intended use cases, via example code;
-- any other venues (such as mailing list, pull requests or issue threads external to the location of the explainer) where the reader may catch up on discussions regarding the proposed feature or features;
-- the alternatives which have already been considered and why they were not chosen;
-- accessibility, security and privacy implications which have been considered as part of the design process.
+2. Proposed Approach:
+Explain the proposed solution or approach to addressing the identified problem.
 
-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.
+3. Practical Use Cases:
+Demonstrate how the proposed solution can be practically applied to address various use cases through the inclusion of example code snippets.
 
-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.
+4. Discussion Venues:
+Provide links to external venues such as mailing lists, pull requests, or issue threads where interested readers can catch up on discussions related to the proposed feature.
 
-## Examples of good explainers
+5. Considered Alternatives:
+Discuss alternative approaches that have been considered and provide reasons for not choosing them. This helps reviewers and stakeholders understand the decision-making process.
 
+6. Accessibility, Security, and Privacy Considerations:
+Highlight any accessibility, security, and privacy implications that have been taken into account during the design process.
+
+7. High-Level Overview for Specification Writing:
+Once there is reasonable consensus on the approach and high-level design, the explainer can serve as a guide for writing the specification, providing an overview of the feature and the user need it fulfills.
+
+8. Author-Facing Documentation:
+After the spec is written and the feature is implemented, the explainer can be used as a basis for creating documentation that helps authors understand and utilize the new feature effectively.
+
+Examples of Good Explainers:
 - [Service Workers](https://github.com/w3c/ServiceWorker/blob/master/explainer.md)
 - [`paymentRequest`](https://github.com/zkoch/paymentrequest/blob/gh-pages/docs/explainer.md)
 - [Web Share](https://github.com/WICG/web-share/blob/master/docs/explainer.md)
@@ -43,30 +51,37 @@ the explainer can then provide a basis for author-facing documentation of the ne
 - [Declarative Shadow DOM](https://github.com/mfreed7/declarative-shadow-dom/blob/master/README.md)
 - [Autoplay Policy Detection](https://github.com/w3c/autoplay/blob/main/README.md)
 
-## Tips for effective explainers:
-
-Since your explainer may be referred to by a range of stakeholders,
-not all of whom are likely to be highly motivated to spend a lot of time on it,
-you should always try to keep your explainer as brief and easy to read as possible.
-
-- Be clear about the **end-user** need, first and foremost.
-  - Sometimes the connection to the end-user need is complicated.  Do explain the connection, even if this requires breaking the "be brief" rule.  (For example, see the [explainer for deprecating document.domain](https://github.com/mikewest/deprecating-document-domain/#a-problem), although even that could perhaps use another sentence explaining why security boundaries are important for users.)
-- Keep it as brief and "skimmable" as you possibly can.
-  - Writing succinctly is harder than writing at length. You might need to write a first draft, and then make one or more editing passes to cut down word count. This is a time investment, but will save time and energy for your readers.
-  - Use bulleted lists where possible.
-  - Draw attention to key points using **bold**. 
-  - Keep your paragraphs and sentences short. Paragraphs should contain one idea only, and likely shouldn't be more than a couple of sentences. Break up large paragraphs as much as possible.
-- Keep the language as simple as possible.
-  - Not all readers will always be fluent English speakers.
-  - Even if they are, they may be reading your explainer while doing three other things, with a headache and a looming deadline.
-  - Be kind to your readers, since you probably want them to be kind to you.
-- Wherever possible, use code examples rather than prose to "show" rather than "tell" your design.
-- If you can and if it serves the document, be generous with diagrams.
-  - A picture is, for most readers, much easier to process than a slab of text.
-  - Always provide text alternatives for readers who may not be able to see images.
-    - Simpler images may be described via an [image alt](https://webaim.org/techniques/alttext/#complex).
-    - More complex images may require a longer description in the form of a footnote or appendix to the document, linked immediately after the image, with a back-link to return to the section containing the image.
-- Help the reader understand which parts of your explainer describe the Web as it is today and which parts of the explainer describe what you are proposing to change.  Explainers often need to explain things about the Web today to give context for the proposal.  A reader who doesn't already know the details should be able to distinguish the context from the proposed changes.
-- As your design evolves, keep track of and make a note of alternatives which have been considered, and your reasons for not choosing them.
-  - You undoubtedly had reasons not to choose those alternatives, but reviewers and other stakeholders may not have that context. Avoid redundant "what about [already-ruled out alternative]" type questions by explaining why those alternatives were ruled out.
-  - Direct readers to the appropriate participation forums, issue tracker, etc.
+Tips for Writing Effective Explainers:
+
+1. Be Concise:
+Since explainers are likely to be read by various stakeholders, strive to keep them brief and easy to read.
+
+2. Clarify the User Need:
+Emphasize the end-user need that your proposed feature addresses, even if the connection is complex. Provide explanations that help readers understand the significance.
+
+3. Maintain Readability:
+Write in a concise and skimmable manner. Use bulleted lists to present information clearly. Employ bold formatting to highlight key points.
+
+4. Use Code Examples and Diagrams:
+Whenever possible, use code examples to demonstrate your design instead of relying solely on prose. Consider including diagrams to aid understanding. Remember to provide text alternatives for images.
+
+5. Simplify Language:
+Keep the language as simple as possible to accommodate readers who may not be native English speakers or who may be reading under time constraints.
+
+6. Be Kind and Considerate:
+Show kindness to your readers, as you would like them to reciprocate. Respect their time and effort.
+
+7. Distinguish Web Context and Proposed Changes:
+Help readers differentiate between the current state of the web and the proposed changes. Provide clear context for the proposal, explaining necessary details about the existing web platform.
+
+8. Document Considered Alternatives:
+Keep track of and explain alternative approaches that were considered but not chosen. This helps reviewers understand the decision-making process and avoids redundant questions.
+
+9. Markdown Format for Transparency and Likability:
+Please provide your explainer as a markdown file alongside the specification. 
+This approach promotes transparency, discoverability, and accessibility, making it easier for readers to access and navigate the content and making it easier to refer to sections of the document during any discussion in the design review issue.
+
+10. Encourage Participation:
+Direct readers to relevant participation forums, issue trackers, or other communication channels to encourage their involvement and feedback.
+
+By following these guidelines, you can create clear, concise, and accessible explainers that effectively communicate your proposed web standards specifications for W3C TAG review.