Thread: I think we need to be careful when saying having a GraphQL API means you don't need to think about documentation and get it for free.
GraphQL definitely gives us a head start, just like JSON Schema / OpenAPI can. However, I kinda of see that as a help to build an API reference more than complete documentation.
REST has the advantage of having resources that usually answer clear use cases, located at a single endpoint. The power of "expressing all possibilities" of a GraphQL server is great, but can also be overwhelming for on boarding users.
I think we could do a better job at documenting GraphQL APIs by providing sample use cases and providing "pre-made" queries for integrators. A server could even have pre-whitelisted persisted queries: Yet again, we're getting VERY close to a REST API again ;)
Great documentation is more than just a reference to all fields and types. This is something I'd like us to get better at GitHub: less focused on types and fields in the documentation, and more on how to accomplish use cases!
