Overhaul how we document the different library flavors #5097
Comments
|
Feature indication of the different "flavors" would be much appreciated! |
|
Slightly offtopic, please point me to another place to ask this if required. I am curious, is there any documentation at all for the |
|
@dit7ya To be honest, I don't know what to make of that package. It was added in a single commit in the middle of the big Apollo Server 2.0 refactoring push 3 years ago. I believe there's only been one change to its source code since then other than just applying the same change to all framework packages. The package doesn't support some of the things the other integrations support like health checks and playground (and uploads, though we are removing that in Apollo Server 3). That we haven't had to iterate on it all either means we did an amazingly perfect job in the first place, or it's not heavily used in practice. That said, the official Cloudflare Workers docs do link to a quickstart repo that uses apollo-server-cloudflare, so it probably has some usage... though that repo has a bunch of open issues suggesting it might not be in perfect shape. Current stats on npmcharts.com show only 231 weekly downloads, compared to 2K for Azure Functions, 5K for Google Cloud Functions, 94K for Lambda, and 966K for Express. (Though maybe there's something odd about CF workers where using a package from them doesn't count towards your npm stats?) Filed #5118 to consider the future of this package as part of AS3. |
|
IMO documentation sites are not appropriate for open source packages. Each package should have a readme containing all documentation required to use that package at that particular commit/version. It should be the primary source of truth for someone trying to figure out how to use that package. When companies go bust or retire software, documentation sites fade from the internet and the open source community using these npm packages without readmes suddenly has no documentation whatsoever. Documentation sites often get out of sync with package versions, or have tricky UX to look up the right version of the docs. In contrast, readme files are version controlled with the package source and it's very easy to view a particular version on npm or GitHub. If a PR changes the public API, it should also include the necessary documentation updates. For my packages, I use JSDoc comments in the source code and Here is an example of one of my packages with a decent readme via JSDoc tooling: https://github.com/jaydenseric/graphql-upload Ideally a user discovers a bunch of packages on npm, use their readmes to decide which one is most appropriate for their project, then use that readme there to get started; all without having to go searching through external documentation sites. It's tiresome when you have to remember what particular webpages you have to visit to read docs for what particular packages; when you have a lot of dependencies you just want to take for granted you can visit their npm or github page and look at a readme. It would be rad if Apollo were to delete their documentation site and focus on quality package readmes. If packages are too complex to understand via even a well maintained readme then that is a huge smell that they are too complex, and should be rewritten to have a more intuitive API or get split into multiple packages with more clearly delineated concerns. Apollo has some of the worst readme's on npm/github. For example: https://www.npmjs.com/package/apollo-server-core
Zero actual documentation. Another Example: https://www.npmjs.com/package/@apollo/server
What does this package do, why does it exist? There is literally nothing to go off. It does a disservice to the npm community to publish low quality readme's like that; these confusing packages show up in Google/DuckDuckGo and npm search results. Related: #5090 |
|
Thanks for the feedback, @jaydenseric! Note that Agreed that |
|
We also need explicit documentation of how to "eject" from |
|
And to link to the ejection from a few places in migration.md (search for 5097). |
Now the "apollo server" reference page is just about ApolloServer (we lose docs for `gql` but that's not the biggest deal; we can add a reference page about other exports later if we want), and the middleware page provides sample code for every middleware and gives advice on which middleware to use. Fixes #5097. (More or less. We could definitely do more work on this front, but this is a good start.)
Now the "apollo server" reference page is just about ApolloServer (we lose docs for `gql` but that's not the biggest deal; we can add a reference page about other exports later if we want), and the middleware page provides sample code for every middleware and gives advice on which middleware to use. Fixes #5097. (More or less. We could definitely do more work on this front, but this is a good start.)
* docs: refactor middleware and ApolloServer docs Now the "apollo server" reference page is just about ApolloServer (we lose docs for `gql` but that's not the biggest deal; we can add a reference page about other exports later if we want), and the middleware page provides sample code for every middleware and gives advice on which middleware to use. Fixes #5097. (More or less. We could definitely do more work on this front, but this is a good start.) * First batch of edits to middleware docs (#5404) * First batch of edits to middleware docs * Incorporate feedback from @glasser * Remaining edits to middleware docs (#5408) Co-authored-by: Stephen Barlow <[email protected]>
|
Fixed in #5396 |
ApolloServer is not a single API: it is provided by a bunch of different packages:
apollo-serverapollo-server-expressapollo-server-lambdaapollo-server-hapi,apollo-server-koa,apollo-server-fastify,apollo-server-micro)apollo-server-cloud-functions,apollo-server-azure-functions)(There's also
apollo-server-cloudflarewhich seems like it should be serverless but is built more like a traditional integration, and also has been barely touched since its introduction.)These packages don't all provide the same APIs! In some cases this is due to the distinctions between "batteries-included" and not. In some cases it's the distinction between "traditional" and "serverless". In some cases it's due to differences between the frameworks themselves (eg, the ability to configure features unique to a framework, or argument types that are the framework-specific request/response objects). In some cases it's just that we haven't implemented a feature for all frameworks.
But our docs don't make it easy to understand this. We don't have comprehensive API docs for each package.
Instead, we have:
apollo-server-lambdaand more about being a guide to using theserverlesstool to install AS on LambdaAlso individual feature doc pages sometimes allude to things that are specific to one API variety; eg, the health checks page provides no hint that
onHealthCheckis an argument toapplyMiddlewareforapollo-server-expressrather than the constructor.We should rework these approaches to have complete and accurate API documentation for each of our integrations, or at the very least for the "top 3" with a clear note that the others may be less fully documented.
The text was updated successfully, but these errors were encountered: