Notes from a talk to WebML WG

[inexorabletash]

The Web Machine Learning group asked me to give a talk on "Spec writing with Bikeshed using the latest WebIDL and Infra standard conventions" event. I wrote up some notes to prepare and thought I should post them somewhere public for posterity. I think they align best with this repo, so dropping them in an issue here so we can maybe migrate them into procspec in the future.

Examples below may be specific to WebNN since that was the audience.

---

Background material:
Writing Procedural Specs
Writing Specifications with Bikeshed
Bikeshed Docs

What have we learned (by making mistakes) that got us here?

• Earlier web specs gave high level description of behavior, e.g. input and output. Turns out a lot of the implementation can be observable and thus lead to compatibility problems. Developers don't test everywhere or read warnings.
• Specs are for a specific audience: implementers; if you try to write for developers, you're gonna have a bad time. They should be looking at MDN.
• If you define anything in two places you have twice the chances of getting it wrong. If you get out of sync, everything is wrong. Prioritize precision over readability.
• Non-normative notes are your friend.
• "domintro" sections help reconcile a lot of the tensions above. They're developer-facing non-normative notes in the spec. Use simpler phrasing, don't worry as much about edge cases, etc.

Important details:

• WebIDL is the interface between your spec and JavaScript. 99.99% of the time your spec shouldn't mention anything related to JavaScript outside of examples. (So nothing Normative). And that 0.01% is REALLY HARD to get right, leads to security issues, etc.
• Spec should be written in terms of Infra types - numbers, strings, lists, ordered maps, etc, with the defined operations.
• Infra is not perfect or complete, you will go beyond it. Look at other specs for inspiration - better to follow precedent. Look at open Infra issues and consider filing issues if you're in novel territory.
• e.g. debate between [[internal slots]] and "has an associated" text.

Bikeshed tips:

• Think of Bikeshed as a compiler for your spec.
  • Like code: the less you write the lower your chances of having a bug
  • Link terms as much as you can. It helps avoid ambiguity. This is like writing strongly-typed code - you'll get errors earlier.
  • Use scopes when linking - scopes are good!
  • Using algorithm blocks correctly gets you error checking - ensures you don't have unreferenced variables, catches some typos, etc.
  • Keep your build error-free. ("--die-on=warning")
  • Prefer markdown to markup - shorter, more likely to catch errors
• It is not perfect:
  • easy to end up with variables in the global scope, can't verify that.
  • can't verify types of inputs/outputs
• Bikeshed is not bug-free, but you can generally work around things.
  • Support definitions in details > summary speced/bikeshed#2649
  • Clicking on method argument names within algorithm definition should highlight them speced/bikeshed#2647
  • Multiple elements have the same ID warning with method overloads speced/bikeshed#2646
• If something is truly a blocker, I can backchannel to @tabatkins
• Lots of hidden heuristics, e.g. if you name an algorithm "foo a bar" you can reference it with "fooing a bar" without having to define a separate link
• Look at the generated indexes:
  • Terms defined by this specification
  • Terms defined by reference - are you referencing the right terms?
    • example in WebNN: "number" references CSS-VALUES-4
    • example in WebNN: "object" references FileAPI
• Look at the references
  • Normative references - are these REALLY what you're depending on?
• Semi-controversial opinion: Don't word-wrap the source; it makes spec diffs painful. Consider breaking after full sentences or within lists.

Ecosystem

• The IDL Index section is consumed automagically to produce "idlharness" tests in Web Platform Tests
  • can test general API shape (inheritance, properties, method lengths)
  • can NOT test argument types, exceptions, etc.
• Speaking of WPT
  • ideally every normative spec change comes with a corresponding WPT change
  • "if it's not tested, assume it's broken"
  • more (positive) pressure to keep the normative parts of the spec tight

Conclusions:

• If you're feeling like writing a spec is like writing code… you're doing it right.
• Consider factoring out common algorithms.
  • … but also YAGNI
  • … and is it going to make the spec harder to read or maintain?

[fdwr]

Semi-controversial opinion: Don't word-wrap the source; it makes spec diffs painful. Consider breaking after full sentences or within lists.

I came to this same epiphany for my own markdowns, improving diffs and making general reordering easier.