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

[codehag]

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]

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]

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

[codehag]

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]

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

[allenwb]

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]

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]

@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]

@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.