Enhanced/Comprehensive Documentation

[dmill]

Hi there! I've been building out an MVP using Relay, and I've loved the structure and philosophy. While I'm not one to ungratefully complain about OSS that is being provided and maintained for me for free, I thought I should share my main pain point with the project since it is leading me to strongly consider switching to something else as I move forward. The Relay docs work when undertaking the most basic functionality, but once things get a little bit more complex I find them to be very hard to follow and incomplete.

Specifically, I had a difficult time understanding the response format that Relay requires/expects my API to return and could never really find this fully documented anywhere. When I did find links to the comprehensive API specification (Example), these still seemed disjointed and disconnected from the "docs" on the main website. I also ran into a lot of trouble when trying to implement updater and optimisticUpdater functions in my mutations, and found myself struggling to cobble together the proper boilerplate with ConnectionHandler.

Again, I'm not trying to bash the project and think y'all are doing great work, but would love to open up a discussion as to how the documentation could be improved to make it easier to troubleshoot and get a project up-and-running.

Thank you!

[alunyov]

Hey @dmill

Thank you for your feedback! Yeah, documentation is one of the current issues and we're trying to fix that. We had a brainstorming session with OSS community week ago or so, to discuss this very issue.
I think @jstejada should share meeting notes for this soon. So, I hope we will be in a better place with docs.

Also, there is an ongoing discussion here about the docs: #2696.

And we always welcome PRs with doc improvements!

[dmill]

@alunyov Didn't see that one in my brief search through the issues. I'll check it out thanks!