tc39
Editorial: Add a link to the collection of historical editions
It was surprisingly hard to find https://www.ecma-international.org/publications/standards/Ecma-262.htm (now https://www.ecma-international.org/publications-and-standards/standards/ecma-262/ ) when researching for this tweet.
I'm not sure if historical editions are so important for so many people that we need to link to them as the second line of the specification. Maybe we could pursue making this information easier to find as part of the TC39 website, at https://tc39.github.io/beta , rather than in the main spec text.
I believe it is important to provide links directly from a document towards those it updates and/or replaces (cf. the "Obsoletes" and "Updates" front matter in RFCs such as 7230). This particular reference could be placed elsewhere in the spec, but to me it seems very appropriate to follow up language like "This… is the tenth edition" with content that describes where to find previous editions.
Let's look into surfacing historical information as part of @jorydotcom 's archiving project. If you want to understand the history of something, there's a lot more to look at than the past annual versions.
I agree, but in my opinion that doesn't invalidate the benefits (I would say "requirements") of providing a link that points from a document towards the content it updates and/or replaces.
I agree that this is perhaps giving too much attention to historical superseded editions. Also, remember that the current official standard is not the same as the current working draft on github. Perhaps a more general statement would be better:
The current and past editions of ECMA-262 is available in several formats at https://www.ecma-international.org/publications/standards/Ecma-262.htm. The current working draft for the next edition is available at https://tc39.github.io/ecma262/ .
This is a more general statement with more information. It says where to look for historic editions but doesn't over emphasize them.
I like that suggestion a lot - especially if we can flip the order, so the current working draft link is mentioned first.
I'm not sure, I'm still skeptical of directing people to the historical editions as the third sentence of the specification. Understanding the history also includes understanding the revision history on GitHub, and the revisions of the docs that Allen made; many intermediate versions have shipped to the web. Many people see the historical spec versions already and draw false conclusions for them. I'd prefer for this to be presented with more clear context, as part of the archival project.
@littledan are you arguing for the https://www.ecma-international.org/publications/standards/Ecma-262.htm link to appear elsewhere in the spec, or for it not to appear in the spec at all?
If the former, then where would you propose if not alongside the already-existing discussion of other editions? I want it to be early but nonintrusive, both to place each revision in its proper context and also to make it easy for someone who has pulled up the wrong edition (e.g., from having bookmarked a now-outdated edition) to quickly correct their mistake.
But if you instead are arguing for the link to not appear in the spec at all, then we just fundamentally disagree and I don't know how to move forward.
@littledan Would you prefer a link to the archival project (when it is ready), possibly at the end of this "history" section?
@zenparsing That sounds like a good idea, yes.
@gibson042 Later in the introduction could be good.
The introduction is currently structured as a self-definition of the document, followed by a history of the language and a final acknowledgement of contributors:
- This standard defines ECMAScript, and is the Nth edition of the ECMAScript Language Specification. Since the first edition in 1997, ECMAScript has taken over the world. It is best known from web browsers, but has also been adopted for server and embedded applications.
- ECMAScript is based on JavaScript and JScript, appearing in all Netscape browsers since Navigator 2.0 and all Microsoft browsers since IE 3.0.
- Development of the Language Specification started in November 1996. The first edition of this Ecma Standard was adopted by the Ecma General Assembly of June 1997.
- (approval of the second edition)
- …
- (changes in previous edition)
- (changes in this edition)
- (acknowledgement of community effort)
- (identification of editors)
@littledan I currently have the link to all editions and formats right after the self-definition and before the history lesson, for easy outbound navigation when someone finds theirself in the wrong place. It obviously doesn't belong in the history, so where would you like it moved? Before the community acknowledgements? After the list of editors? Under a new Introduction subheading?
Maybe right after the history? I think the historical editions are logically part of the history and make sense to explain as such.
Right, but the history provides edition-by-edition detail in chronological order. So "after the history" in practice will mean right after a description of changes in the latest edition, very far removed from the document's self-description and immediately before community acknowledgments. Do you really think that's better than immediately before the detailed history, where it is now?
Although I don't want to make committee unanimity required for editorial changes, I would urge the editor not to accept this as-is, and if such an archival link is provided at all, for it to be much further down in the document, as discussed upthread.
(don’t mind the netlify rule failures; I’m trying to get it configured for #1525)
The rendered spec for this PR is available at https://tc39.es/ecma262/pr/1335.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}