Participate

Introduction

Your explainer is a living document that describes the current state of your proposed web platform feature, or collection of features.

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

As your work progresses, the explainer can help facilitate multi-stakeholder discussion and consensus-building by making clear:

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.

Examples of good explainers

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