[spec review] 1 - Introduction + Consistency

[flagxor]

Detail oriented review of draft text:
http://webassembly.github.io/spec/core/bikeshed/index.html#introduction%E2%91%A0

Also includes front-matter + overall document consistency.

Try to be ready to discuss issues by the next in person WG meeting.

[lukewagner]

Random driveby:

• § 1.1: "WebAssembly is an open standard developed by a W3C Community Group that includes representatives of all major browser vendors." - This sentence was meaningful in early readmes/intros when wasm was just getting started but it seems out of place permanently backed into a W3C spec (especially once wasm starts showing up in non-browser embeddings)

[liminzhu]

Yeah I agree. Early on it was nice to show that all browsers were behind it but it's time for wasm to become a standard rather than perceived as a browser thing. Plus the standard is also technically developed by the WG?

It's a small sample, but I looked up service worker and webRTC spec and neither include similar text.

[liminzhu]

Did an attentive pass on intro and a rough pass on the rest of the core spec for consistency issues. Overall the spec is in very good shape! Some feedback:

• [spec] Debuggability as design goal #759
• nit - there are lots of arbitrary uses of colon or period before bullet points or formulas. (e.g. 1 2 3 4). Maybe we can use colon in places where phrases like 'the following' or 'as follow' are used immediately before points or formulas and use period otherwise, or just apply some general principle. Certainly low pri as it doesn't really affect readability or anything much.
• nit - If a footnote is displayed as a paragraph longer than a line, the number is placed next to the center of the paragraph rather than the start (example), which is a bit odd. Not sure if this is a bikeshed limitation or not.

[rossberg]

Thanks for the review!

• nit - there are lots of arbitrary uses of colon or period before bullet points or formulas. (e.g. 1 2 3 4). Maybe we can use colon in places where phrases like 'the following' or 'as follow' are used immediately before points or formulas and use period otherwise, or just apply some general principle. Certainly low pri as it doesn't really affect readability or anything much.

I tried to follow rules as I seemed to remember them from editing notes for articles, but I may well have messed it up. Happy to address concrete suggestions or review patches. :)

• nit - If a footnote is displayed as a paragraph longer than a line, the number is placed next to the center of the paragraph rather than the start (example), which is a bit odd. Not sure if this is a bikeshed limitation or not.

It is. I opened #794 to track it.

[binji]

#794 is still not addressed, but it seems as though the rest of the issues are addressed. Closing.