nodejs.org
nodejs.org copied to clipboard
nodejs
Modify /api to a page that points to both LTS and stable APIs
There are two other issues (#305 and #307) related to modifying the front page to point to both sets of documentation, and modifying /docs to do the same. This one is specifically for addressing /api.
Currently, /api points to the stable release, v5. It needs to be modified, most likely into a page that has links to both the LTS release, v4, docs, as well as the stable v5 API docs.
I agree with @shelleyp (including other two issues) how the docs should be linked.
How about adding a dropdown with all versions as part of the left side (at least all LTS versions plus $latest)?
I think the issue is should the /api point to latest (Stable) or current LTS? Most people using Node in production are probably going to be using LTS. I can't imagine production environments that won't use LTS, other than some very edgy environments.
Then each API page has to have a listing, preferably along the top, for all active LTS and/or Stable releases. The left side won't work, because it lists the different core modules.
Example: I search on "Node" and "console". Right now, I'm getting the api for Node 5.0, and the console. Peachy, but I'm mainly working in 4.2.2, the LTS. To find it, I actually have to go to the front page of the Node site, and look for the docs associated with the LTS installation, open them, and then find console.
This means, by my estimates, the majority of people will have to go through a double-search process to find the documentation they need, while the minority developers wanting New! get an immediate result.
It is not efficient. It is not user-friendly.
https://nodejs.org/api/ is an alias to the docs directory of the latest nodejs distribution on the server - it is not a unique version of the docs that can be customised.
Some options:
- leave as is. Doing google searches for nodejs docs will return results that are for the latest stable release
- change it to point to the docs for the latest lts release
- change
/apito go to https://nodejs.org/en/docs/ that contains links to the docs for all versions.
I think your idea of redirecting /api to /docs is probably the only equitable one.
The reason why I believe so is that I don't see "current" as the Stable release. Most companies, and therefore most developers, will likely be using LTS, because of the stability. One would assume this, then, is "current". Downplaying LTS just confuses people, makes it seem like LTS is this backwards oldster that no one in the Node Foundation really likes.
Others, though, will disagree. They'll think people should be using Stable. Stable has all the latest, New! And this is one debate that will probably never have a successful resolution.
Besides, get people used to the new way of doing things. There are, at a minimum, two releases in active support at any time. More than two eventually. Break people's habit of thinking of Node as one release.
I don't think this is likely to happen in the current site, but is a possibility for the website redesign. Is there an appropriate repository that I can transfer this issue to? /ping @nodejs/website-redesign
https://nodejs.org/api/ is an alias to the docs directory of the latest nodejs distribution on the server - it is not a unique version of the docs that can be customised.
Is this a symlink on the server or something like that? @nodejs/build
https://nodejs.org/api/ is an alias to the docs directory of the latest nodejs distribution on the server - it is not a unique version of the docs that can be customised.
Is this a symlink on the server or something like that? @nodejs/build
Yes. More specifically it's an nginx config that redirects "/api" to the "latest" symlink in docs, which is created by https://github.com/nodejs/nodejs-latest-linker on the download/web server every time a release is promoted.
Just an off-topic, on nodejs.dev handling multiple versions is already a working feature. Right now we're only building the latest docs, as older docs (such as v14) have some invalid markdown stuff, but I believe we're close to get v14 and v16 docs working.
The idea is to have only currently maintained (current, lts and maintenance) versions to be hosted on nodejs.dev and any other version is redirected to the archive.
Marking this on hold as there's no actionable we can do here, but this should be magically solved once (if we at all) incorporate the new API docs design available on nodejs.dev
I'm closing this for now, unfortunately the changes need to be done on our NGINX side of things. At least, on the website redesign any API links from search results will redirect to the LTS documentation.