Revision to explainer explainer #39

torgo · 2023-07-11T14:16:45Z

I've tried to make this more readable and I've also included a new item on making explainers a markdown file.

LeaVerou · 2023-07-11T14:56:20Z

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


I liked Introduction better, it's more standard

I feel like it's better to be explicit about what this page is about.

I feel this should be the 1st level heading, with the 2nd level heading being "Introduction".

LeaVerou · 2023-07-11T14:57:04Z

explainers/index.md

-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.


Maybe also developer-facing materials or research?

explainers/index.md

LeaVerou

Changes look good.
I wonder if we should ask for multi-stakeholder review here, like TC39 proposals. This is useful for anyone reading the explainer.

Also, something about describing the user experience, end-to-end. That could be a self-contained code example, or even a GUI interaction, depending on what the feature is.

alice

I like these edits overall, thank you for sprucing this up! I am concerned about losing some of the detail, as commented.

alice · 2023-07-11T21:09:10Z

explainers/index.md


-In the early phases of design, this may be as simple as a collection of goals and a sketch of one possible solution.


I hope you'll consider leaving some version of this in. My intent was to illustrate what "living document" means, and encourage beginning an explainer as soon as work begins on a standards project.

I agree the second clause of the sentence could use some work...

alice · 2023-07-11T21:11:46Z

explainers/index.md

+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.


Please consider keeping the extra suggestions on text alternatives.

alice · 2023-07-11T21:13:05Z

explainers/index.md

+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.


Separated from the point about simple language, this point is a bit vague. Could you add more to "Respect their time and effort by ..."?

Suggested change

Show kindness to your readers, as you would like them to reciprocate. Respect their time and effort.

Show kindness to your readers, as you would like them to reciprocate. Respect their time and effort by using some of the techniques described above (code examples, diagrams and images) to “show” rather than “tell” where possible. Show how the feature will be experienced by web users and how it will be used by web developers.

@alice what do you think? Trying to channel our recent discussions on Fenced Frames especially, @LeaVerou.

alice · 2023-07-11T21:15:21Z

explainers/index.md

- 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.


I think these points are important to include for people who don't necessarily do a lot of prose writing.

alice · 2023-07-11T21:17:40Z

explainers/index.md

-  - 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.


This in particular was added after I read one too many explainers with paragraphs that went on for days.

I've been a bit over-zealous in simplifying this down. Will re-incorporate these as you've suggested.

Co-authored-by: Lea Verou <lea@verou.me>

torgo · 2023-07-12T09:40:28Z

explainers/index.md


-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:


Suggested change

Key Components of an Explainer:

In the early phases of design, an explainer may be as simple as a collection of goals and a sketch of one possible solution. As the specification matures, the explainer should focus on the following key components:

@alice wdyt?

torgo · 2023-07-12T09:42:12Z

explainers/index.md

-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.


Suggested change

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.

Provide links to external venues such as mailing lists, pull requests, or issue threads where interested readers can catch up on discussions or find developer-facing materials or research related to the proposed feature.

chrishtr · 2023-07-21T16:49:10Z

explainers/index.md


-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.


I think it would be very useful to expand on this with a paragraph or two on "why write an explainer?" They are indeed very useful, but a lot of people don't understand why, and it'd be very useful to have a compelling explanation, ideally with a worked example.

Also, refer to the "tips" section right at the top, and note that it's important to read the tips because they will "save you time and help to make your explainer as effective as possible".

chrishtr · 2023-07-21T16:50:05Z

explainers/index.md


-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.


I think this needs more detail, and an example to show how it works. It also needs some sentences that explain why it's so important to start with the user-facing problem and not immediately get into the technical details.

chrishtr · 2023-07-21T16:51:52Z

explainers/index.md


-## Examples of good explainers
+5. Considered Alternatives:


Nit: "Alternatives Considered" (change order of words)

tantek

These look like excellent improvements, conditional on keeping/including all the suggested improvements from @alice

Revision to explainer explainer

c4c7227

I've tried to make this more readable and I've also included a new item on making explainers a markdown file.

torgo requested review from LeaVerou and plinss July 11, 2023 14:17

LeaVerou reviewed Jul 11, 2023

View reviewed changes

explainers/index.md Outdated Show resolved Hide resolved

LeaVerou approved these changes Jul 11, 2023

View reviewed changes

alice reviewed Jul 11, 2023

View reviewed changes

Update explainers/index.md

af47058

Co-authored-by: Lea Verou <lea@verou.me>

torgo commented Jul 12, 2023

View reviewed changes

chrishtr reviewed Jul 21, 2023

View reviewed changes

LeaVerou mentioned this pull request Jul 22, 2023

text-wrap: pretty w3ctag/design-reviews#864

Open

1 task

tantek approved these changes Feb 8, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revision to explainer explainer #39

Revision to explainer explainer #39

torgo commented Jul 11, 2023

LeaVerou Jul 11, 2023

torgo Jul 12, 2023

LeaVerou Jul 12, 2023

LeaVerou Jul 11, 2023

LeaVerou left a comment

alice left a comment

alice Jul 11, 2023

alice Jul 11, 2023

alice Jul 11, 2023

torgo Jul 12, 2023 •

edited

torgo Jul 12, 2023

alice Jul 11, 2023

alice Jul 11, 2023

torgo Jul 12, 2023

torgo Jul 12, 2023 •

edited

torgo Jul 12, 2023

torgo Jul 12, 2023

chrishtr Jul 21, 2023

chrishtr Jul 21, 2023

chrishtr Jul 21, 2023

chrishtr Jul 21, 2023

tantek left a comment


		In the early phases of design, this may be as simple as a collection of goals and a sketch of one possible solution.

	Show kindness to your readers, as you would like them to reciprocate. Respect their time and effort.
	Show kindness to your readers, as you would like them to reciprocate. Respect their time and effort by using some of the techniques described above (code examples, diagrams and images) to “show” rather than “tell” where possible. Show how the feature will be experienced by web users and how it will be used by web developers.


		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:

	Key Components of an Explainer:
	In the early phases of design, an explainer may be as simple as a collection of goals and a sketch of one possible solution. As the specification matures, the explainer should focus on the following key components:

	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.
	Provide links to external venues such as mailing lists, pull requests, or issue threads where interested readers can catch up on discussions or find developer-facing materials or research related to the proposed feature.

Revision to explainer explainer #39

Are you sure you want to change the base?

Revision to explainer explainer #39

Conversation

torgo commented Jul 11, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LeaVerou left a comment

Choose a reason for hiding this comment

alice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

torgo Jul 12, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

torgo Jul 12, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tantek left a comment

Choose a reason for hiding this comment

torgo Jul 12, 2023 •

edited

torgo Jul 12, 2023 •

edited