doc: add link to ABI guide

[gabrielschulhof]

Provides a link from the N-API reference to the guide discussing ABI stability in greater depth.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

@gabrielschulhof build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/1136/pipeline

[vsemozhetbyt]

It seems this should be an absolute link URL to work from the site.

https://nodejs.org/en/docs/guides/ is provided by the https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides , not by the https://github.com/nodejs/node/tree/master/doc/guides .

[gabrielschulhof]

@vsemozhetbyt I've updated the link, but of course as a result it's 404 until the guides get updated. I assume this happens with the next release of Node.js.

[vsemozhetbyt]

I may be wrong, but should not we relocate the guide from https://github.com/nodejs/node/tree/master/doc/guides to https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides for it to be accessible from the https://nodejs.org/en/docs/guides/ ? Otherwise, we can link to the https://github.com/nodejs/node/blob/master/doc/guides/abi-stability.md directly,

If I am not mistaken, docs in https://github.com/nodejs/node/tree/master/doc/guides are mostly for the Node.js Collaborators, while docs in the https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides are mostly for the Node.js users and developers.

[vsemozhetbyt]

cc @nodejs/documentation and @nodejs/website re the question above. Should the difference be documented somewhere if it is valid?

[Trott]

If I am not mistaken, docs in https://github.com/nodejs/node/tree/master/doc/guides are mostly for the Node.js Collaborators, while docs in the https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides are mostly for the Node.js users and developers.

That's correct. If it's in doc/guides then it's for us. If it's in doc/api then it's for users.

[Trott]

Oh, and if it's a generalized guide for users, then it should go in a totally different repo: https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides

[Trott]

Items in doc/guides do not end up on the website. They are for internal consumption. External-facing guides should be moved to https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides instead.

[gabrielschulhof]

@Trott I've opened nodejs/nodejs.org#1828 and #23303 to move the doc. I guess this PR depends on those two landing.

[Trott]

Blocked by nodejs/nodejs.org#1828. Once that lands, this can land. Fortunately, website PRs can be merged pretty quickly...

(I don't think #23303 needs to land before this does.)

[Trott]

Also: The whole "things called 'guides' are in two different places and mean subtly different things, and oh yeah the website is generated in this repo over here except for the docs which are generated over here".... If there's some way that information could have been something could have been surfaced naturally, I'd love to hear what it is. Because that stuff is confusing and probably only a few people know it.

Maybe the guides directory in this repo can be renamed to something that makes it clear they are internal to the project and/or moved out of docs?

Maybe a bot can comment on any PR that adds a new file to the docs/guides letting the user know that these guides are for internal use and if they meant to create something for end users, then they should close this PR and open a new PR over in this other repo?

Other ideas?

[vsemozhetbyt]

Maybe it is worth to open an issue to discuss?

[gabrielschulhof]

nodejs/nodejs.org#1828 has now landed, so removing the "blocked" label.

[gabrielschulhof]

@vsemozhetbyt @nodejs/n-api PTAL

[gabrielschulhof]

CI: https://ci.nodejs.org/job/node-test-pull-request/17703/

[gabrielschulhof]

Landed in 157d507.