Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revision to explainer explainer #39

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

torgo
Copy link
Member

@torgo torgo commented Jul 11, 2023

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

I've tried to make this more readable and I've also included a new item on making explainers a markdown file.
@torgo torgo requested review from LeaVerou and plinss July 11, 2023 14:17
@@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I liked Introduction better, it's more standard

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe also developer-facing materials or research?

explainers/index.md Outdated Show resolved Hide resolved
Copy link
Member

@LeaVerou LeaVerou left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

@alice alice left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please consider keeping the extra suggestions on text alternatives.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@torgo torgo Jul 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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:
Copy link
Member Author

@torgo torgo Jul 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alice wdyt?

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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Examples of good explainers
5. Considered Alternatives:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@tantek tantek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants