Informative notes

# Axel Rauschmayer (4 years ago)

On 22 Jan 2015, at 10:29 , Brendan Eich <brendan at mozilla.org> wrote:

ECMA-357 (E4X) pioneered informative-first prose sections, not found in ECMA-262 Ed. 3, and as a direct consequence, had too many imprecise or even inaccurate informative notes, which (turns out) were misread as normative, or simply otherwise caused confusion.

OTOH, I find rationales and complete terminology very important for talking about and understanding the spec (but I do know that that would incur even more work). At the moment, reading the spec feels like figuring out undocumented source code; rationales have to be deduced by going though the TC39 meeting notes and the es-discuss archives (or, in the case of proxies, Tom’s papers). A companion book to ECMA-262 may be the ideal solution, but the problem is that the audience/market for such a book is small. And Allen’s plate must be full enough as it is.

# Axel Rauschmayer (4 years ago)

Follow-up thought: people still link to the (completely outdated) proposals on the wiki, because they are often very readable. Is it conceivable to better maintain proposals for ES2016+ ? Or would that be too much work for the champions?

# Benjamin (Inglor) Gruenbaum (4 years ago)

Follow-up thought: people still link to the (completely outdated) proposals on the wiki, because they are often very readable.

I think people mostly link to them because they are rank pretty well in search results and are confined to a single problem in a readable way.

I think the way PHP manages RFCs (wiki.php.net/rfc) - while not nearly as accurate (IMO) as ES proposals has some really interesting things in its template and encouraging community feedback on proposals while they're worked on is very valuable.

For example - I don't need to know or understand what [[ReferenceGet]] is to understand something written in this sort of style: wiki.php.net/rfc/combined-comparison-operator

# Brendan Eich (4 years ago)

Benjamin (Inglor) Gruenbaum wrote:

For example - I don't need to know or understand what [[ReferenceGet]] is to understand something written in this sort of style: wiki.php.net/rfc/combined-comparison-operator

Not bad -- we are using gists and github markdown but could build that up to mimic the PHP structure and style a bit, if enough people find value in it.

BTW, that particular combined-comparison-operator proposal (the "spaceship" operator, <=>) has been discussed at TC39 meetings in passing. I think dherman is the likely champion, but I could be wrong!

# Benjamin (Inglor) Gruenbaum (4 years ago)

Not bad -- we are using gists and github markdown but could build that up to mimic the PHP structure and style a bit, if enough people find value in it.

PHP's ircmaxell told me they're using WikiText - for example: wiki.php.net/rfc/combined-comparison-operator?do=edit&rev=0

It shouldn't be too hard to do something similar with markdown - although I think a centralised site similar to php's for holding all proposals currently discussed as well as a place for people to leave comments or directing them to this mailing list.

I don't mind taking a shot at getting something like this up - would people use it?

# Domenic Denicola (4 years ago)

From: es-discuss [mailto:es-discuss-bounces at mozilla.org] On Behalf Of Brendan Eich

Not bad -- we are using gists and github markdown but could build that up to mimic the PHP structure and style a bit, if enough people find value in it.

FYI the new hotness is Ecmarkup + Ecmarkdown as in e.g. arv.github.io/ecmascript-object-observe or bterlson.github.io/Array.prototype.includes :)

Regarding the general idea of motivation/introductory materials, I think the new process explicitly encourages this, and indeed most new proposals include that in their README or similar. Examples:

We could consider trying to standardize but we're still in the exploration phase I think. Good to experiment and see what people like. (For example, I want to steal that sidebar-TOC from the PHP RFC.)

# Benjamin (Inglor) Gruenbaum (4 years ago)

This looks sweet Domenic!

Especially things like tc39/Array.prototype.includes/blob/master/README.md

It would be great it if were standardised and made more readable (the sidebar for example)

# Domenic Denicola (4 years ago)

From: es-discuss [mailto:es-discuss-bounces at mozilla.org] On Behalf Of Benjamin (Inglor) Gruenbaum

I think a centralised site similar to php's for holding all proposals currently discussed as well as a place for people to leave comments or directing them to this mailing list.

Way ahead of you: tc39/ecma262

# Axel Rauschmayer (4 years ago)

Regarding the general idea of motivation/introductory materials, I think the new process explicitly encourages this, and indeed most new proposals include that in their README or similar. Examples:

I agree, these are all great. They’ll be an important complement to the spec.