Documentation for core Apollo Client functions?

[villander]

Now that the apollo client no longer has documentation for VanillaJS, how will we do it?

The React Apollo documentation has now become official. But it is also not feasible to do an entire documentation of that in Ember.js. We need a better strategy.

[josemarluedke]

We should consider writing a guide for integrating Ember with Apollo. I suggest using something like https://github.com/ember-learn/ember-cli-addon-docs that has a very good foundation for documentation and has the ability to have live examples.

[bgentry]

Hey @stubailo @jbaxleyiii, what are your thoughts on this? Previously we were able to point folks to the raw Apollo Client documentation which was pretty solid. But it seems that was never really upgraded fully for 2.0 and is indeed replaced by links to the React docs (here).

It's pretty unlikely that we have the bandwidth to re-document everything important about the Apollo Client libs. That time would also be better spent improving our integration.

Thoughts?

[bgentry]

I opened #106 to track creating our own documentation site.

However, that does not cover what we should do about documenting core Apollo Client functionality. It does appear that only the platform/framework-specific docs are kept up-to-date on the Apollo website.

Would love to hear from @stubailo or @jbaxleyiii about how we should handle that. Is it the expectation that every framework-specific Apollo Client lib has to separately document the core functionality?

[evans]

@bgentry apologies for the lack of response! Thank you for brining up the issue. James and Sashko are super busy with the React side of things. Looks like we may be able to make a big push for documentation in a coming sprint. I hope we are able to make your life easier during that. Could you help us by opening an issue on Apollo Client with a list of the functionality/functions that need more or better documentation?

It will definitely help us figure out what the holes are and what core functionality is important to you. In terms of generic documentation, we currently have some generic setup docs, apollo-link basics, basic info on the cache, error handling, direct cache access
and an API reference. Hope this list helps your process. If anything sticks out as needing to be improved directly or made more discoverable, please include it in the issue

[alexking]

Most of the API links in README.md are broken now, the style changed from

Broken (what README.md uses):
http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient.watchQuery

Redirects To (the also broken):
https://www.apollographql.com/docs/react/reference/index.html#ApolloClient.watchQuery

Correct URL:
https://www.apollographql.com/docs/react/api/apollo-client.html#ApolloClient.watchQuery

Despite having /react/ as part of the url, they seem to be a pretty generic API reference - can update those if we'd like to make browsing the readme a bit easier.

[bgentry]

@alexking yes, please PR any improvements you can! Thank you.

I'd still like to build out our own doc site too (#106) but haven't had any time to work on that.