Use

https://dlaliberte.github.io/bikeshed-intro

In

1. Resolve |promise| with |some-value|. 

"resolve" can have markup to link to the correct promise dgn.

Resolve "else" vs. "otherwise" (which is used in many specs). Options include:
(1) Require "else" and "else if";
(2) Require "otherwise" and "otherwise if";
(3) Allow both (but require that the spec must be consistent).

Also, see Ternary Operator for another use of "otherwise".

What are recommendations?

"there's like 4 different ways of saying that a frame is cross origin in specs and I can never wrap my head around them. Might be nice to have a section there as it comes up in many specs. "

Relevant spec: https://html.spec.whatwg.org/multipage/browsers.html
In particular, sections 7.1 and 7.2. Among the notable terminology: "unit of related browsing contexts" and "IsPlatformObjectSameOrigin(O)"

See whatwg/html#2112
but it's really unclear in the end what the use cases are. If someone could assemble them that would be helpful. In general what I'm unsure of is what the X and Y are in "X is cross-origin with Y". Sometimes it's frames, sometimes it's platform objects, sometimes it's JavaScript code, sometimes it's network resources...

Some part overlap with Infra

https://infra.spec.whatwg.org/

What (if anything) does it make sense to merge?

In English, the construction "run these substeps in parallel: A, B, C" means "run A, B and C in parallel with each other". However, in specifications, it has the specific meaning of running A, B and C sequentially on a background thread (that runs in parallel with the main thread).

Assigning the phrase to mean the exact opposite of its standard meaning in English is... unfortunate.

https://w3c.github.io/IndexedDB/#evaluate-a-key-path-on-a-value

readme to point out that it's an amalgam of Bikeshed, Infra (algorithms) and web platform stuff.

the call for "procedural spec"s is basically asking for spec to be more specific and detailed (e.g, by including pseudo code algorithms and explicitly specifying each step). It came about as a reaction to the fairly loose style that had become prevalent in specs.

The loose style (where specs are mostly prose) led to situations where the behavior looked like it was well-specified, but inadvertently omitted some details which led to different implementations.

need to look at the spec+test artifacts together

See whatwg/html#3038

Current:

1. Let p be a new Promise
2. Run the following substeps in parallel:
   a. Let foo be something awesome, with sprinkles.
   b. Resolve p with foo
3. Return p

I notice HTML uses:

1. Let p be a new Promise
2. Return p, but continue running these steps in parallel.
3. Let foo be something awesome, with sprinkles.
4. Resolve p with foo

I don't know when this usage arrived (over a year ago?) but it seems to have slightly lower cognitive overhead. This would e.g. dramatically reduce the amount of indentation in Service Workers. Maybe @annevk or @domenic can comment on the preference for this style?

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.
  • speced/bikeshed#2649
  • speced/bikeshed#2647
  • 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?

From Tab:
A reasonably common practice, which Bikeshed explicitly deals with, is to define this as an attribute, but with [[foo]] naming - double square brackets. This groups it with the IDL definitions in indexes, and you can ref it with the IDL linking syntax, like {{[[foo]]}}.

This also explicitly associates the private slot with the interface, which is exactly what it's actually doing.

"I guess there are lots of little conventions around e.g. how to do setters + getters, how to do constructors, how to do optional arguments, etc. that could be documented... Maybe just via linking to examples"

https://garykac.github.io/procspec/

I saw @annevk removing the "substeps" usage from Encoding:

whatwg/encoding#108

Yay for less wordiness.

• When obvious e.g. following "while", "then" or "otherwise", no additional wording is used.
• Otherwise (e.g. for "queue a task", "switch", etc) just use "steps" instead of "substeps"