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:
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.
paymentRequestEventListenerOptionsSince 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.
Start with a clear explanation 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.
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.
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.
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.
Wherever possible, use code examples rather than prose to “show” rather than “tell” your design.
Use diagrams to aid understanding. 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.
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.
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.
By following these guidelines, you can create clear, concise, and accessible explainers that effectively communicate your proposed web standards specifications for W3C TAG review.