Title: Writing Effective Explainers
Shortname: explainer-explainer
Level: none
Status: NOTE-ED
Group: tag
Repository: w3ctag/explainer-explainer
URL: https://w3ctag.github.io/explainer-explainer/
TR: https://www.w3.org/TR/explainer-explainer/
Editor: Matthew Tylee Atkinson, w3cid 68793, Samsung https://www.samsung.com
Editor: Jeffrey Yasskin, w3cid 72192, Google https://google.com, jyasskin@google.com
Former Editor: Daniel Appelquist, w3cid 35086, Invited Expert
Complain About: accidental-2119 yes, missing-example-ids yes
Markup Shorthands: markdown yes, css no
Assume Explicit For: yes
Boilerplate: conformance no
Required IDs: introduction, good-explainers, tips, end-user-need, write-simply
Required IDs: describe-proposal, alt-text, alternatives, history, deep-linking, template
Abstract: An explainer introduces a problem that a group of people are trying to solve,
and helps everyone with an interest in the target problem find consensus on a good way to solve it.
!Participate: [Github repository](https://github.com/w3ctag/explainer-explainer)
!Participate: [Issues](https://github.com/w3ctag/explainer-explainer/issues)
!Explainer Template: [https://github.com/w3ctag/explainer-explainer/blob/main/template.md](https://github.com/w3ctag/explainer-explainer/blob/main/template.md)
Metadata Include: Issue Tracking no, Feedback no
Metadata Order: !*, *
# Introduction # {#introduction}
Your explainer is a living document that describes the current state of your proposed web platform feature, or collection of features.
It helps everyone with an interest in the target problem find consensus on a good way to solve it.
In the early phases of design, this may be as simple as a collection of goals and a sketch of one possible solution.
By the time you request a TAG early design review,
it should contain the following key components:
1. Discussion Venues:
Link to venues where readers can discuss this proposal.
1. User-Facing Problem:
Describe the problem that your proposed feature aims to solve **from an end-user's perspective**.
1. Proposed Approach:
Explain the proposed solution or approach to addressing the identified problem.
1. Practical Use Cases:
Show example pieces of code that use the proposed solution to solve the user-facing problems.
1. Alternatives Considered:
Describe other ways the problem might be solved and why you prefer your proposal.
1. Accessibility, Internationalization, Privacy, and Security Considerations:
Highlight any accessibility, internationalization, privacy, and security implications
that have been taken into account during the design process.
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.
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 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)
to do their reviews.
# Examples of Good Explainers # {#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)
- [Viewport API](https://github.com/WICG/ViewportAPI/blob/gh-pages/README.md)
- [`EventListenerOptions`](https://github.com/WICG/EventListenerOptions/blob/gh-pages/explainer.md)
- [Intersection Observer](https://github.com/w3c/IntersectionObserver/blob/master/explainer.md)
- [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 Writing Effective Explainers # {#tips}
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.
## Explain the End-User's need ## {#end-user-need}
Start with a clear description of the end-user problem you're trying to solve,
even if the connection is complex or
you discovered the problem by talking to web developers who emphasized their own needs.
Use screenshots, mockups, wireframes, diagrams, and/or other visuals when possible, [with alt text](#alt-text).
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),
and see [[#boilerplate-user-benefit]] for text to
explain why security boundaries are important for users.
Some features are intended to help authors and
have no effect on end-users aside from websites being developed more easily.
If your feature doesn't cause any harm or benefit to users,
use [[#authoring-user-benefit|the boilerplate for ease of authoring]].
## Write Simply ## {#write-simply}
Use common words to help readers who aren't native or even fluent English speakers.
Be concise.
Expect readers to skim.
They may be doing three other things, with a headache and a looming deadline,
and you don't want them to miss your points.
- Use **bold** to draw readers' eyes to the most important points.
(And *italics* for intra-sentence emphasis.)
- Use bulleted or ordered lists when listing things.
- 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.
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.
## Describe Your Proposal Clearly ## {#describe-proposal}
Show how your proposal changes the end-to-end user experience
using screenshots, diagrams, and code examples.
Connect these into a narrative of what steps users currently follow,
and how your proposal improves that.
A picture is, for most readers, much easier to process than a slab of text,
but 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.
If your proposed design depends on other non-consensus features, list them.
## Show the Alternatives That You Considered ## {#alternatives}
As your design evolves, keep track of and make a note of alternatives which have been considered.
Explain what makes them worse for the web than your primary proposal.
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.
Format the alternatives in a way that makes them easy to understand.
There are a few ways to do this.
First, you can structure the alternative as:
```markdown
### Name of the alternative
Explanation of the alternative design.
#### Advantages
* List
#### Disadvantages
* List
#### Reason for rejection
Why do you feel the disadvantages outweigh the advantages?
```
Alternatively, you can collect a set of [Architectural Decision Records](https://adr.github.io/) as files in your repository.
[https://adr.github.io/madr/](https://adr.github.io/madr/#overview) may contain a good template,
but we don't have enough experience to recommend this structure in particular.
If you have a directory of ADRs, link them from this section of your explainer.
Occasionally, an alternative will be clearly unacceptable for some reason,
for example because it's strictly worse than another alternative that is analyzed in detail in another section.
In that case, if you're sure the reviewers will agree,
you can skip the sub-sections and describe just the reason for rejection.
## Connect to History ## {#history}
Many important end-user problems have a history of failed and incomplete attempts to solve them.
Look for and draw on those ideas when developing and explaining your own proposal.
Link to all prior art in either
your [alternatives considered](https://github.com/w3ctag/explainer-explainer/blob/main/template.md#alternatives-considered) section
or your [references and acknowledgements](https://github.com/w3ctag/explainer-explainer/blob/main/template.md#references--acknowledgements).
## Enable Easy Deep Linking ## {#deep-linking}
You should host your explainer as HTML at a stable, readable URL,
ideally next to where the specification is expected to land.
Use a format
that makes it easy for reviewers to link directly to sections inside the document,
like Markdown or HTML.
It's fine to use a host like GitHub that automatically renders Markdown.
----
By following these guidelines, you can create clear, concise, and accessible explainers that effectively communicate your proposed web standards specifications for W3C TAG review.
# Appendix A: Markdown Template # {#template}
See this rendered at
[https://github.com/w3ctag/explainer-explainer/blob/main/template.md](https://github.com/w3ctag/explainer-explainer/blob/main/template.md).
path: template.md
highlight: markdown
# Appendix B: Boilerplate Explanations of User Benefit # {#boilerplate-user-benefit}
Some classes of features are meant to
help authors achieve some kind of user benefit,
like security, accessibility, or performance,
more easily.
Explainers for these features should say why that general area helps users,
but explainer authors should
spend most of their time explaining why the feature improves the area.
This section provides some boilerplate for some common areas
so that authors don't need to rewrite it every time.
## Accessibility ## {#accessibility-user-benefit}
> This feature is meant to improve website accessibility,
> which ensures all users can browse the web,
> even if they need to interact with their computers
> differently from the majority.
## Ease of Authoring ## {#authoring-user-benefit}
End-users come before authors
in the [[design-principles#priority-of-constituencies|priority of constituencies]],
so when explaining features designed for authors,
you need to clearly establish that there's no negative effect on end-users.
For example, [[css-nesting inline|CSS nesting]] primarily makes it easier to write stylesheets,
and the potential reduction in file sizes wasn't measured as part of justifying the feature.
On the other hand,
a feature like [[privacy-preserving-attribution inline|Privacy-Preserving Attribution]]
isn't in this category because it does have some negative effect on end-users
(via bandwidth costs and information exposure under its privacy budgets),
so its specification argues that these costs are justified by greater end-user benefits.
> This feature is meant to make it easier to write websites
> and to have no negative effects on end-users.
> When websites are easier to write,
> users get more of them
> and don't need to pay as much (in fees or ads)
> to access them.
> [If it's not obvious:]
> See <a href="#later-section">below``
> for an analysis of why the proposed solution doesn't harm end-users.
## Performance ## {#performance-user-benefit}
> This feature is meant to improve website performance,
> which helps users waste less time waiting
> and helps users on low-end devices and slow connections
> browse the web at all.
## Security ## {#security-user-benefit}
> This feature is meant to improve website security,
> which reduces the frequency of breaches that compromise user data.