tc39/how-we-work

Moving "How to read ECMAScript specification text" to this repo

codehag opened this issue · 8 comments

codehag commented

Hi Everyone, I have been in touch with Timothy Gu, the author of "How to read the ECMAScript specification" -- he was wondering if this is something that could be moved to a TC39 owned repository. What do people think about making it part of this repo?

devsnek commented

Definitely +1 to moving it. I wonder though, could we take it a step further and put this guide (or something similar) in the actual spec?

ecmageneva commented

Do not put it directly into the spec, but somewhere close to it. To have a kind of "ECMAScript for Dummies" type of book / document is not bad. What would be needed, that some people read the content to see if everything is ok. E.g. with quick reading I saw that the ISO/IEC version of ECMA-262 Ed. 5 ( ISO/IEC 16262) has been withdrawn on the ISO/IEC side because we have that replaced with the ECMA-414 based solution (ISO/IEC 22275). https://www.iso.org/standard/73002.html

  • 👍1
codehag commented

We should check that the information is accurate. I think this would make a good addition to how-we-work documents after it has been vetted. With the website going online, I don't think we will need to put this guide into the spec, we can just surface it so that people find it more easily.

gesa commented

Would anyone be willing to volunteer to review & edit the how-to in order to get it published in this repo?

allenwb commented

I read it when first published. I thought it was pretty good but did see a few nits that I didn't have time to comment on at the time.

I unlikely to have time to review it before September.

TimothyGu commented

I’d be happy to receive comments in any way, including GitHub issues on the repository itself as well as this thread. Please let me know!

littledan commented

@TimothyGu I've read your document, and it seems really good to me as is. Would you be interested in making a PR to move the document there into a Markdown file here?

TimothyGu commented

@littledan I would much prefer if we could move it into a repository on its own. This is due to two reasons:

  1. Right now, the documentation has a lot of cross references. I'd prefer using a spec generator rather than manual linking. (I understand it looks more like a W3C document than a TC39 one right now, but I'm working on the styling.)
  2. I still consider the document to be a draft. It needs some updates, and only talks about some aspects of runtime semantics. I'd like to talk at least a bit about syntax-directed operations. Being in its own repository allows me to better iterate on it.
  • 👍1