doc: Add blurb to N-API recommending the use of badges

[ddlan]

Add blurb to N-API documentation indicating that we recommend the use of badges
Fixes: #22796

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[cjihrig]

I won't block this, but I don't think it belongs in the docs.

[mhdawson]

@cjihrig just wondering if you have alternate suggestions where you think it would make more sense to publicize this kind of info?

[mhdawson]

@gabrielschulhof FYI in case you have not seen this yet.

[vsemozhetbyt]

@ddlan Did you close it intentionally?

[ddlan]

@vsemozhetbyt Yes, would it be better for me to leave it open?

[vsemozhetbyt]

Well, I see two approvals and no blocking objections, so this can be landed if I am not mistaken)

[cjihrig]

just wondering if you have alternate suggestions where you think it would make more sense to publicize this kind of info?

Sorry, I missed that response. I don't have an alternative suggestion, I just don't feel like it belongs in the official Node docs. Shields.io and other services offer a bunch of different badges, but we don't suggest using any other ones. And, why do I need a badge? Why not just write it out in the project's README. Again, I don't feel strongly enough to block it, but it seems odd.

[gabrielschulhof]

@cjihrig we're taking this step to drive adoption of N-API. We do so after having received feedback in support in nodejs/admin#221.

[gabrielschulhof]

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

[addaleax]

Please don’t include external resources in our official API docs, since it leaks usage data to the image hoster.

That being said, I agree with @cjihrig in that this is not really something that should go into our official documentation.

[ddlan]

@addaleax In that case, what's the best way to add the images to the documentation?

[addaleax]

I suppose that if we do add this, downloading them to doc/api_assets and including them from assets/ would be the best way?

[danbev]

@addaleax With the latest commit, would you be alright with landing this?

[addaleax]

@danbev I don’t know … it still seems out-of-place in our Node.js core documentation. This is API/reference docs, not a guide for repository/package management.

[addaleax]

Have you verified that this works in the make doc output? I think most of our assets are included via assets/, not some ../-prefixed path

[gabrielschulhof]

@ddlan could you please redo this PR against the doc branch at abi-stable-node, and add the blurb to README.md in that branch instead? That might be a better place for it.

[Trott]

It seems like this has not reached consensus and conversation has stalled. We should either close it or escalate to the TSC for a decision. I'm going to close it, but feel free to leave a comment if you feel that escalation to the TSC is the better approach. (I'm personally of the opinion that this is somewhat out of place in our docs and is better suited for another repo, as suggested by @gabrielschulhof.)

[Trott]

@ddlan Thanks for the pull request. I hope the experience was not discouraging and I hope you will continue to submit pull requests for Node.js!