This repo is for the development of explainers from Mozilla contributors. Mozilla Explainers can start with as little as a sentence summarizing a user-relevant problem and how a new technology could help solve it. The W3C TAG Explainer provides a basic outline, examples, and tips for developing explainers.
In general we expect to focus on developing explainers that:
We strongly prefer external feedback only on explainers that are in their own repo (see Explainer file progress).
If you see something in a Mozilla Explainer that you want to suggest changing or fixing, please file an issue describing the problem and suggested resolution, not a pull request. Exception: minor non-substantive or typographical changes may be submitted as PRs.
Explainers migrated to an incubation group or standards working group.
Explainers we are no longer pursuing, have been superseded, or have been incorporated into another explainer.
Start your explainer with at least:
If your explainer is a counter-proposal to an existing public explainer or group proposal, your minimum explainer should include enough additional sections to provide a useful contribution to the existing conversation around the problem(s) being solved, and approaches already being explored. For example, if someone else has proposed an API to solve the problem(s) your explainer describes, your minimum explainer should include at least sections 1-5 (see below), especially existing proposal flaws, and why/how we can do better.
Expand your explainer with the following sections, in order:
This repo is for developing explainer files until ready for external feedback, or archival if we decide an explainer is no longer worth pursuing.
For new minimum explainers (those missing any of sections 2 through 6), we expect that those sections are added within 2-4 weeks of publishing your minimum explainer, using pull requests.
When ready to solicit external feedback on an explainer:
Alternatively, archive an explainer file if:
Iterate on an explainer repo, improving the explainer until there is broader interest to migrate it to an incubation or standardization group, or alternatively archive it for the same reasons as above.
Iterate by:
When there is consensus on an incubation or standardization destination for the explainer, follow the destination’s process for migrating into it.
Useful reading before/while writing an Explainer:
Real world examples of explainers from other organizations (alphabetical by URL) — check these for similar problems being solved, opportunities to collaborate rather than create a new explainer: