Rename explainer to proposal
marcoscaceres opened this issue · 3 comments
As we start spec development, we are likely to make breaking changes. As such, the explainer won't match the spec anymore.
It would probably be better to create a fresh explainer that is always sync'ed with the spec. That is, require that all pull requests that include author-impacting changes include a changes to the explainer.
- rename the current explainer -> proposal.md or, probably better... move it to historicalAndEvolution.md (which we could probably just move to the wiki).
- create a new explainer.md
- add GitHub pull request template to enforce the change to explainer.
Can you cut down the explainer to just what you're planning to implement and why?
I think keeping it in sync with the evolving spec will waste time (and sometimes forgotten).
Can you cut down the explainer to just what you're planning to implement and why?
Depends... what gets implemented (i.e., exposed to the web) will depend on what we have consensus on in the CG/WG. Put differently, I don't know what the final shape is going to be until we all agree to it.
I think keeping it in sync with the evolving spec will waste time (and sometimes forgotten).
Generally, I would agree (and I'm totally guilty of this with other specs)... but a lot of people seem to appreciate them, and some folks ask for them, like that W3C's TAG, as part of the wide review process.
I think if we are disciplined, and enforce keeping it up to date with the pull request template, it might be ok.
I can take responsibility for keeping it up to date. If it fails spectacularly, we can just point people to the introduction of the spec and examples.
I would certainly appreciate it. I find it useful myself and use it as the resource to point developers to if they start asking for more details