Thread by @slightlylate

A few months ago I wrote up some of the lessons we've learned the hard way in standards-based feature development. One area I glossed over was the role of "Explainers" (thread!): docs.google.com/document/d/1cJ…

ICYMI, the blog series is here:

"Part 1: The Lay of the Land": infrequently.org/2018/06/effect…
"Part 2: Threading the Needle": infrequently.org/2018/06/effect…

Unlike most product features, standards-track features require (at least) two design documents: one for the public surface area of the feature and another for the implementation of that surface area within a given codebase.

*NEITHER OF THESE DOCUMENTS IS A FORMAL SPECIFICATION*

This is often disorienting for folks who are new the process or who have previously implemented specs but haven't designed new features.

Coming at the problem of feature design with the tools of an after-the-fact implementer frequently leads engineers astray! Previous, successful designs had formal specs; why not this new idea?

After all, specs fully detail every aspect of the prospective design, tightly defining terms and details that will need to be sorted out at some point.

That is, it seems like a time-saving device to write down your idea in the language and structure of a formal spec.

Nothing could be further from the truth!

Feature designers are looking for *needs* to meet and *constraints* to satisfy.

Fully specifying the minute details of a broad-strokes sketch introduces designers to the wrong level of detail, drowning them in complexity.

To get to a full understanding of the constraints on the design space, you have to shop your design around to prospective users, engage them in the process of writing end-to-end code samples, and in general "swimming in" a proposal.

Well-run design processes do multiple passes of this iteration process, and designs change dramatically as constraints and needs become iteratively clearer.

Aside: anyone who presents finely detailed aspects of a design they just implemented in their runtime (and presumably are about to ship) is a metaphorical danger to themselves and others. They're wrong but they don't know how (yet).

What this highlights is that the design phase of a feature requires malleability. Ideas need to be cheap enough to throw away. Over-tightly describing the details of a system creates pressure in the opposite direction: it increases the cost of change.

Specs are also written with a different audience than high-level design docs: high-level designs outline the problem being solved (and for whom), describe how the proposed design compares to alternative approaches, and close the loop by showing how the proposal satisfies needs.

Detailed specs, OTOH, describe to fellow implementers how the internals of a proposed design are rationalised against the spec-world. Nobody actually lives in spec-world, it turns out...yet like Klingon or Elvish, the language of it is beguiling to some and highly specific.

And that specificity is needed. If something doesn't make spec-world sense, it'll eventually be modified such that it does (sometimes in a breaking way; which is bad)

Which is the long way of saying that you need web developers to understand your design so they can pass judgement on whether or not it actually solves a real problem they have *before* investing the time to translate the high-level sketch into Specish (Specklish? Specese?)

The role of the Explainer is to be that pre-spec design doc. It's an essential part of a well-functioning design process and something we look for feature designers to produce at the @w3ctag because it helps us review the spec's *intent*.

This, incidentially, is part and parcel of why you're seeing so many new web specs lead with this sort of high-level, end-to-end description of their functionality:

github.com/WICG/page-life…
github.com/WICG/web-locks
docs.google.com/document/d/1k0…
github.com/WICG/Backgroun…

Well-written Explainers include loads of sample code and zero WebIDL. This makes folks most-fluent in Specish uncomfortable, but it's the correct choice for all of the previously discussed reasons. IDL doesn't tell a web developer anything about the system; sample code *does*.

The role of Explainers also changes over time. When incubating designs graduate to formal standards bodies, ship in multiple implementations, and earn their hard-fought place on MDN, perhaps they aren't needed. But at every moment until all those conditions are met, they help.

...and they help a gradually shifting constituency. Early on, they help sell the problem as much as the solution, building developer and implementer enthusiasm at the possibility of solving the issues.

Later in the process, they serve as front-matter for a formal spec. Opinions differ in various forums as to the role and necessity of example code and non-normative text within specs. Explainers provide a home for that context regardless.

Lastly, the iteration and evolution of an explainer captured in source control helps to document the process by which the final deliverables came to be. This can be hugely valuable to future designers.