Open inexorabletash opened 9 months ago
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.
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?
Important details:
Bikeshed tips:
Ecosystem
Conclusions: