Recording design rationales?
We try to record these in the strawman or proposal page itself:
doku.php?do=search&id=+rationale
I agree that a global summary/review could be good too if it is maintained/curated assiduously. Possibly this is better done based on distributed and champion-curated rationale parts when we are closer to done with ES6.
The examples you cite, <| and classes, are not baked fully yet (at least as far as syntax goes for <|, but it sounds like also for the function special-case; and in various ways for classes). This may be related to the need for design rationale docs. Not that rationales would clinch the proposals as-is, rather that we'll have consensus and robust rationales at about the same point on the hermeneutic spiral (assuming we choose the right paths!).
Allen wrote a rationale doc for the design of the ES5 Object meta-programming API:
es3.1:rationale_for_es3_1_static_object_methodsaug26.pdf
It is still helpful but not complete -- in particular no reconciliation with ES5 user experience, reflection (pun!) on configurable, etc. defaults being falsy => Object.create/defineProperty being verbose, etc.
I find that when my memory fails me, I have to follow breadcrumbs in the wiki and even here on es-discuss. This too suggests rolling up a consolidated rationale document (wiki markdown, nothing fancy) when we are closer to done.
On Mar 25, 2012, at 3:54 AM, Axel Rauschmayer wrote:
Now that the memories are still fresh – would it make sense to record how some of the design decisions were arrived at? I’d expect that to help with future feature additions and with reducing the amount of questions being asked on es-discuss. Examples: What names of the <| operator have been rejected and why? Why don’t class declarations have feature X? Etc.
FWIW, I record huge amounts of this kind of information in my private notes. It's not private out of any desire for secrecy, but simply because I try to get everything down as soon as I can, before my pitiful brain forgets it all, and as a result it's generally a mess of chicken scratch. Making it fit for consumption would take a lot of work.
To be sure that would be yet more work (which should be done by the proposal authors, I guess), so I’m not sure it’s worth it, but it would be a great resource for educating the masses.
I hope to do this as much as possible, but it's the kind of thing that makes more sense to do when the dust settles, at least in any given area. Otherwise you end up wasting time polishing things that are about to change anyway. And as we go along I do try to state publicly any important rationale that needs to be explained in order to justify the decisions made. But design at the scale of a language covers an unimaginably huge space of alternatives, so it's just not always feasible to capture all the micro- and macro-decisions in real time and in a polished form.
On Mar 26, 2012, at 3:07 , David Herman wrote:
To be sure that would be yet more work (which should be done by the proposal authors, I guess), so I’m not sure it’s worth it, but it would be a great resource for educating the masses.
I hope to do this as much as possible, but it's the kind of thing that makes more sense to do when the dust settles, at least in any given area. Otherwise you end up wasting time polishing things that are about to change anyway. And as we go along I do try to state publicly any important rationale that needs to be explained in order to justify the decisions made. But design at the scale of a language covers an unimaginably huge space of alternatives, so it's just not always feasible to capture all the micro- and macro-decisions in real time and in a polished form.
Agree 100%. Writing this down too early would be inefficient. Once the ECMA-262 draft stabiles it could be a bit like its shadow document.
Brendan’s idea of a Markdown wiki sounds right, too. It doesn’t have to have even close to the same polish as ECMA-262.
I would love to see rationales captured in this manner but my experience is that efforts to consistently capture such information tend to fall by the wayside as a project progresses towards completion. It becomes a simple question of prioritization. Do you spend time documenting the rationale for decisions or do you push on towards completion to meet the target deadline. The ES3.1 Object methods document really is most comparable to what we now try to capture on the Wiki. However, both then and now, once a feature moves into the the actual specification there is less motivation (and time) to also keep the Wiki proposals up to date. I've occasionally thought about trying to writeup more approachable feature summaries of what has actually been incorporated into the draft spec. but the same time management issue arise. Is it better to write explain what is going into the draft or move on to the next set of spec. work?
I suspect what is really needed to make this work is the dedication of someone who wants to see this happen but who isn't actually on the critical path for completion of the actual spec.. For example, it would be wonderful if somebody decided right now that they wanted to author an annotated version of the ES6 spec. that included design rationales. Then they would have a strong motivation to focus capture rationale information as work on the actual spec. progressed. This would be a great opportunity for anyone who wanted to be the Brian Kernighan of ES6.
Now that the memories are still fresh – would it make sense to record how some of the design decisions were arrived at? I’d expect that to help with future feature additions and with reducing the amount of questions being asked on es-discuss. Examples: What names of the <| operator have been rejected and why? Why don’t class declarations have feature X? Etc.
To be sure that would be yet more work (which should be done by the proposal authors, I guess), so I’m not sure it’s worth it, but it would be a great resource for educating the masses.