Guide to developing well-written proposals

[littledan]

Building on @ljharb 's https://github.com/tc39/template-for-proposals , we could document how a well-written proposal should be made. @DanielRosenwasser wrote,

I've discussed with @bterlson and @rbuckton about the need for background, motivating examples, and potential usage for new proposal documents. Much of the time, it's not clear for outsiders what problems a given proposal is trying to solve.

I think this is a great idea. Ideally, a proposal's README or other supporting documents should describe those. In my opinion, those should be updated as a proposal advances. These can sometimes accidentally get out of date; issues and PRs from other contributors can be a big help here (this could be documented too).

[mathiasbynens]

Big +1 here. Additionally, proposals should include an “implementations” section in their README, linking to bug reports.

[ljharb]

My personal preference has been, once stage 1 is achieved, to file an issue called "Path to Stage 4" that tracks the entire stage process, including implementations, and update it as I go. Here's some examples:

• Stage 4! proposal-object-values-entries#14
• Path to Stage 4! proposal-object-getownpropertydescriptors#9
• Path to Stage 4! proposal-string-pad-start-end#23
• Path to Stage 4! proposal-promise-finally#18
• Path to Stage 4! proposal-string-matchall#21

[littledan]

Parts of this are addressed by #46 , though that doesn't cover the "path to Stage 4" part.

[littledan]

#53 includes @ljharb's issue template. What we're still missing, though, is a guide to well-written spec text.