Writing Effective Explainers

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

2. User-Facing Problem: Describe the problem that your proposed feature aims to solve from an end-user’s perspective.

3. Proposed Approach: Explain the proposed solution or approach to addressing the identified problem.

4. Practical Use Cases: Show example pieces of code that use the proposed solution to solve the user-facing problems.

5. Alternatives Considered: Describe other ways the problem might be solved and why you prefer your proposal.

6. Accessibility, Security, and Privacy Considerations: Highlight any accessibility, security, and privacy implications that have been taken into account during the design process.

Follow the 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, 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.

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.

2. Examples of Good Explainers

• Service Workers

• paymentRequest

• Web Share

• Viewport API

• EventListenerOptions

• Intersection Observer

• Declarative Shadow DOM

• Autoplay Policy Detection

3. Tips for Writing 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.

3.1. Explain the End-User’s 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.

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, although even that could perhaps use another sentence explaining why security boundaries are important for users.

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

3.3. Describe Your Proposal Clearly

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.

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.

3.4. Show the Alternatives That You Considered

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.

3.5. Connect to 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 considered alternatives section or your references and acknowledgements.

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

See this rendered at https://github.com/w3ctag/explainers/blob/main/template.md.

# [Title]

## Authors:

- [Author 1] ([Affiliation 1])
- [Author 2] ([Affiliation 2])
- [etc.]

## Participate
- [Issue tracker]
- [Discussion forum]

## Table of Contents [if the explainer is longer than one printed page]

[You can generate a Table of Contents for markdown documents using a tool like [doctoc](https://github.com/thlorenz/doctoc).]

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Introduction

[The "executive summary" or "abstract".
Explain in a few sentences what the goals of the project are,
and a brief overview of how the solution works.
This should be no more than 1-2 paragraphs.]

## User-Facing Problem

[What is the **end-user need** which this project aims to address?]

### Goals [or Motivating Use Cases, or Scenarios]

- [A bulleted list of goals can help with comparing proposed solutions.]

### Non-goals

[If there are "adjacent" goals which may appear to be in scope but aren't,
enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]

## User research

[If any user research has been conducted to inform the design choices presented,
discuss the process and findings.
We strongly encourage that API designers consider conducting user research to
verify that their designs meet user needs and iterate on them,
though we understand this is not always feasible.]

## Proposed Approach

[Explain the proposed solution or approach to addressing the identified problem.
Do not include WebIDL in this section.
Show example code using your approach.]

[Where necessary, provide links to longer explanations of the relevant pre-existing concepts and API.
If there is no suitable external documentation, you might like to provide supplementary information as an appendix in this document, and provide an internal link where appropriate.]

[If this is already specced, link to the relevant section of the spec.]

[If spec work is in progress, link to the PR or draft of the spec.]

### Dependencies on non-stable features

[If your proposed solution depends on any other features that haven't been either implemented by
multiple browser engines or adopted by a standards working group (that is, not just a W3C community
group), list them here.]

### Solving [goal 1] with this approach

```js
// Provide example code - not IDL - demonstrating the design of the feature.

// If this API can be used on its own to address a user need,
// link it back to one of the scenarios in the goals section.

// If you need to show how to get the feature set up
// (initialized, or using permissions, etc.), include that too.
```

### Solving [goal 2] with this approach

[If some goals require a suite of interacting APIs, show how they work together to achieve the goals.]

[etc.]

## Alternatives considered

[This should include as many alternatives as you can,
from high level architectural decisions down to alternative naming choices.]

### [Alternative 1]

[Describe an alternative which was considered,
and why you decided against it.
This alternative may have been part of a prior proposal in the same area,
or it may be new.
If you did any research in making this decision, discuss it here.]

### [Alternative 2]

[You may not have decided about some alternatives.
Describe them as open questions here, and adjust the description once you make a decision.]

### [Alternative 3]

[etc.]

## Accessibility, Privacy, and Security Considerations

[Highlight any accessibility, security, and privacy implications that have been taken into account
during the design process.]

## Stakeholder Feedback / Opposition

[Implementors and other stakeholders may already have publicly stated positions on this work. If you can, list them here with links to evidence as appropriate.]

- [Implementor A] : Positive
- [Stakeholder B] : No signals
- [Implementor C] : Negative

[If appropriate, explain the reasons given by other implementors for their concerns.]

## References & acknowledgements

[Your design will change and be informed by many people; acknowledge them in an ongoing way! It helps build community and, as we only get by through the contributions of many, is only fair.]

[Unless you have a specific reason not to, these should be in alphabetical order.]

Many thanks for valuable feedback and advice from:

- [Person 1]
- [Person 2]
- [etc.]

Thanks to the following proposals, projects, libraries, frameworks, and languages
for their work on similar problems that influenced this proposal.

- [Framework 1]
- [Project 2]
- [Proposal 3]
- [etc.]