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!):https://docs.google.com/document/d/1cJs7GkdQolqOHns9k6v1UjCUb_LqTFVjZM-kc3TbNGI/edit?usp=sharing …
-
-
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?
Show this thread -
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.
Show this thread -
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.
Show this thread -
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.
Show this thread -
Well-run design processes do multiple passes of this iteration process, and designs change dramatically as constraints and needs become iteratively clearer.
Show this thread -
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).
Show this thread -
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.
Show this thread -
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.
Show this thread -
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.
Show this thread -
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)
Show this thread -
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?)
Show this thread -
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*.Show this thread -
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: https://github.com/WICG/page-lifecycle … https://github.com/WICG/web-locks https://docs.google.com/document/d/1k0Ua-ZWlM_PsFCFdLMa8kaVTo32PeNZ4G7FFHqpFx4E/edit … https://github.com/WICG/BackgroundSync/blob/master/explainer.md …
Show this thread -
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*.
Show this thread -
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.
Show this thread -
...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.
Show this thread -
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.
Show this thread -
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.
Show this thread
End of conversation
New conversation -
Loading seems to be taking a while.
Twitter may be over capacity or experiencing a momentary hiccup. Try again or visit Twitter Status for more information.
& Web Standards TL; Blink API OWNER
Named PWAs w/
DMs open. Tweets my own; press@google.com for official comms.