Make readme a bit more friendly for new users

Hey, 👋

I’m finally trying this package (with hooks) instead of apollo mess and have some suggestions:

The biggest one is lack of examples - using Api section to gather pieces of examples in a whole picture is pretty hard for a new user and examples section suggests visiting another repos with next.js examples which also doesn’t really help in a plain koa + graphql-api-koa project.

Some examples in the docs, before Api section - not codesandbox or other repo links, just some plain md examples with basic things - set up provider, write a query, run a query, run a mutation. They would really help.

Second suggestion is to move apollo comparison to bottom maybe - it’s kinda big and you have to scroll a lot to get to setup/usage sections and is not needed for people, who don’t use apollo or just want to quick start with this package.

Thanks and sorry for the issues, just sharing my thoughts from a new user perspective. As an author, it’s sometimes not obvious to see this because you are familiar with the package. I think this changes may help new users a lot 😃

[eurobob]

@jaydenseric You don’t think it’s too bad because you wrote it. It makes perfect sense to you. That doesn’t make it inherently intuitive. Piecing it together from the API is a tough task, and even your two steps before omit certain knowledge. How do I connect to a specific graphql server?

[vladshcherbin]

The readme Setup and Usage sections are right; to get started, all you need to do is:

1. Create a single GraphQL instance and use GraphQLProvider to provide it for your app. This should wrap your router/routes.
2. Use the useGraphQL React hook in your components to make queries and mutations.

This is exactly what I’m talking about - there are steps but no examples to quickly see what it looks like or copy paste to try it.

Check for example react-apollo, while it has a website with a nice step by step get started page, there is also a usage section in the docs, also with a step by step example. This is what really helps to get started, at least for me 😃