grpc / grpc/grpc-node

@grpc/grpc-js documentation discovery needs streamlining

Open
#1,540 3 comments 2 reactions 0 assignees View on GitHub
package: @grpc/grpc-js
Dominant language
TypeScript
Stars
4.8k
Forks
716
Avg merge
2d 3h
Merged PRs (30d)
10

Description

### Is your feature request related to a problem? Please describe.
I'm unable to easily documentation for `@grpc/grpc-js`.

### Describe the solution you'd like
I think the following would help me and any other engineer trying to learn to use this project:

- The [@grpc/grpc-js npm page](https://www.npmjs.com/package/@grpc/grpc-js) should link to a documentation page
- The [@grpc/grpc-js github page](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js) should link to a documentation page
- The [grpc.io Node.js page](https://grpc.io/docs/languages/node/) should be updated to contain docs for `@grpc/grpc-js`, instead of `grpc`
- The [Basics Tutorial](https://grpc.io/docs/languages/node/basics/) page should contain up to date `@grpc/grpc-js` examples
- The [Node.js gRPC Library](https://grpc.github.io/grpc/node/) has a broken API Documentation link. Currently it just links to itself. It's also counter-intuitive that the top navigation is the most important and that the side navigation and body content on the landing page isn't useful.

### Describe alternatives you've considered
Lots of google searches. Eventually I had to dig into the test suite to find out how to use certain methods.

### Additional context
A Node.js developer looking to use gRPC will first land on either the GitHub page or the npm package page. The flow from getting to the package page to the underlying docs page is very painful. Once the developer does arrive at the docs page they're greeted with docs for the deprecated `grpc` module. For example, [there is no explanation](https://grpc.github.io/grpc/node/grpc.Server.html#bind__anchor) that `Server#bind` will not work with `@grpc/grpc-js`.

Modifying the docs to contain more real-world examples would be nice. Instead of documenting each method, document sets of methods and provide a full working consumer and producer example (I'll gladly donate the examples I'm building for my upcoming book Distributed Node.js).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.