How to handle Editions?

[ehuss]

There should be guidelines for how to handle Editions.

My recommendation: The primary text of the document should document the latest edition. When something is only available in a specific edition (like "async"), mention that up-front. When there is a change in behavior between Editions, edition-specific rules should be added which specify what the change is to the older edition relative to the present.

However, that is not a perfect solution. It can create some awkwardness (like "For the 2015 Edition, disregard rules X, Y, and Z, instead …").

Alternate approaches we struggled with in the Reference are:

• Only document 2015 within the main text, and then anything added in future additions are "extensions" on top of that.
• Any situation where there is a change in edition behavior is shown as an alternation ("in the 2015 Edition, .... In the 2018 Edition, ....").

I do not particularly like those options, though.

[lylythechosenone]

I think an ideal user experience would be to see each edition separately, e.g. via a dropdown menu. That way, a user could view only the edition they wish to know about.

However, this would mean a lot of duplication, so I think internally an "extension" method would be the way to go. We could have a full 2015 version, then 2018 and 2021 patches that just replace some parts of the full 2015 version. I think that could be relatively easy to write while still having good UX.

Maybe having an additional page that explains the differences between editions would be worthwhile.