Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
doc: add links to alternative versions of doc #10958
Each page of the api documentation should have links to other versions
Affected core subsystem(s)
Jan 24, 2017
I didn't give it a +1 in the original issue, at least I see no signs I did :-). I just CCed it to the website group.
The docs we have right now for 7.x are better to use for 4.x than than the 4.x docs were.
This is likely to misdirect people into thinking that node is like express, http://expressjs.com/en/4x/api.html, where you should always look at the docs for the version you are using.
I won't object if others find this useful, but I also won't approve.
Except you won't really know that was a breaking change, unless it was the intoduction or removal of an entire API (because we don't document major changes other than that). And many of the doc improvements apply to older releases. We'd have to start being really rigorous about backporting docs. Currently, the don't backport clean to 4.x because of the .markdown to .md rename, so 4.x docs are no longer the best reference for the features in 4.x. I guess I'm saying I don't think we maintain the LTS docs rigorously enough, and we don't break the node API very much, so this isn't as useful as http://expressjs.com/en/4x/api.html vs http://expressjs.com/en/3x/api.html, and it may be dangerous to suggest we do.
On the other hand, maybe this will force us to backport all doc improvements more consistently, which would be a good thing.
I filed the original issue for this. @sam-github the idea isn't to be able to figure out what is different but to easily be able to find relevant documentation. Each major version is a major version specifically because something in an outward API changed. If i am writing code for 4.x (or even 6.x) I need to be able to quickly look up docs for that version. Right now this is hard - if you google something you always get latest. It should be trivial to get linked to the version of the docs for the API you are working with
The node 7 docs are not helpful when writing code for node 4 (or even node .12 if you are still supporting such a thing).
@toddself spelling corrections in the thrown Error messages are semver-major
OK, I don't object to this, it sounds easy and like some people will find it useful, but I should point out that when the documentation is improved on master, as it often is, for features going all the way back to before LTS (including docs of APIs that existed in 4.x but were not doced), that does NOT guarantee that the docs get backported.