Overhaul how we document the different library flavors

ApolloServer is not a single API: it is provided by a bunch of different packages:

• The batteries-included apollo-server
• The most popular “traditional” framework integration apollo-server-express
• The most popular “serverless” framework integration apollo-server-lambda
• Other traditional framework integrations (apollo-server-hapi, apollo-server-koa,apollo-server-fastify, apollo-server-micro)
• Other serverless framework integrations (apollo-server-cloud-functions, apollo-server-azure-functions) (There’s also apollo-server-cloudflare which 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:

• READMEs for individual packages
• The apollo-server API reference page which is a mish-mosh of documenting shared APIs, apollo-server-specific APIs, and other framework APIs in vague ways
• The integrations page which just lists the middleware and shows one Express example
• The deployments pages like the Lambda one which are less about documenting apollo-server-lambda and more about being a guide to using the serverless tool to install AS on Lambda
• Just reading the source or using your editor’s ability to understand the TypeScript types (this is the only way to fully know the methods and options for all the packages now)

Also individual feature doc pages sometimes allude to things that are specific to one API variety; eg, the health checks page provides no hint that onHealthCheck is an argument to applyMiddleware for apollo-server-express rather 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.

[jaydenseric]

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 jsdoc-md (via a package prepare:jsdoc script that updates the readme “API” section) to make sure documentation is colocated with the source code, linted to be present and accurate using eslint-plugin-jsdoc. This also has a pleasant side effect of having nice rich descriptions and code examples, etc. in editor IntelliSense.

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: https://github.com/apollographql/apollo-server/issues/5090

[glasser]

Thanks for the feedback, @jaydenseric!

Note that @apollo/server specifically is not a released package; we published one alpha once when we were heading down the direction of a package rename, which is no longer planned for v3 (but perhaps for later). I don’t know if there’s a great option here — perhaps deprecate the package on npm?

Agreed that apollo-server-core is a bad README, thus the #5090 that you found.