Informative notes
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?
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
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!
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?
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:
- tc39/Array.prototype.includes/blob/master/README.md
- arv.github.io/ecmascript-object-observe/#intro
- rwaldron/exponentiation-operator
- lukehoban/ecmascript-asyncawait
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.)
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)
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
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.
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.