Standard proposal format?

[mathiasbynens]

What should it look like?

See http://yehudakatz.com/2011/09/13/a-proposal-for-es-next-proposals/ by @wycats for some inspiration.

[domenic]

For consideration: I personally enjoy the format being used for domenic/promises-unwrapping. Here are its key features, IMO:

• README.md is the main spec text, suitable for direction incorporation into the spec.
  • The only non-spec-text part it contains is a "Status" <h1>; since we don't want people getting the wrong impression, this is important enough to infringe on spec territory.
  • There's one other special <h1>, "Deltas to Other Areas of the Spec."
  • The rest is meant to map to top-level ECMAScript spec sections.
• docs/ contains any supplementary information: explainers, design documents, guidance, etc.
  • I could see maybe making Explainer.md a sibling of README.md, since it's so important. But I like being able to stuff most or all of the other documentation into a separate folder.
  • Having a folder encourages the creation of several small documents instead of stuffing everything into one or two large ones.
• reference-implementation/ contains a prollyfill in whatever format the spec author finds most useful.
  • For me, that was a Node 0.11+ version, with tests, that used especially to really nail down the semantics. For @lukehoban, it's some Sweet.js macros. Whatevs.
  • Maybe we could encourage a README.md in this subdirectory to explain how to use the reference implementation.

Not adamant about any of these details, but I think it could provide useful input. I guess what I find most important is that README.md be the actual spec text, and that the spec text be separate from supplementary docs.

[domenic]

For consideration: I personally enjoy the format being used for domenic/promises-unwrapping. Here are its key features, IMO:

• README.md is the main spec text, suitable for direction incorporation into the spec.
  • The only non-spec-text part it contains is a "Status" <h1>; since we don't want people getting the wrong impression, this is important enough to infringe on spec territory.
  • There's one other special <h1>, "Deltas to Other Areas of the Spec."
  • The rest is meant to map to top-level ECMAScript spec sections.
• docs/ contains any supplementary information: explainers, design documents, guidance, etc.
  • I could see maybe making Explainer.md a sibling of README.md, since it's so important. But I like being able to stuff most or all of the other documentation into a separate folder.
  • Having a folder encourages the creation of several small documents instead of stuffing everything into one or two large ones.
• reference-implementation/ contains a prollyfill in whatever format the spec author finds most useful.
  • For me, that was a Node 0.11+ version, with tests, that used especially to really nail down the semantics. For @lukehoban, it's some Sweet.js macros. Whatevs.
  • Maybe we could encourage a README.md in this subdirectory to explain how to use the reference implementation.

Not adamant about any of these details, but I think it could provide useful input. I guess what I find most important is that README.md be the actual spec text, and that the spec text be separate from supplementary docs.

[rauschma]

It’d be nice if every proposal did have some kind of repository, with a structure like the one proposed by domenic. SIMD (currently stage 3) doesn’t, but seems to have the necessary material for setting one up. Its proposal URL is currently: https://docs.google.com/presentation/d/1MY9NHrHmL7ma7C8dyNXvmYNNGgVmmxXk8ZIiQtPlfH4/edit

[rauschma]

It’d be nice if every proposal did have some kind of repository, with a structure like the one proposed by domenic. SIMD (currently stage 3) doesn’t, but seems to have the necessary material for setting one up. Its proposal URL is currently: https://docs.google.com/presentation/d/1MY9NHrHmL7ma7C8dyNXvmYNNGgVmmxXk8ZIiQtPlfH4/edit

[ljharb]

@rauschma the SIMD proposal is here: https://github.com/tc39/ecmascript_simd

[ljharb]

@rauschma the SIMD proposal is here: https://github.com/tc39/ecmascript_simd