Urql: Punch up the URQL site

[jherr]

The URQL documentation site needs to be more immediately useful. Have a look at the Material-UI site:

Right on the home page they have installation and usage, right below the big logo. That's what people want to know; how do I install it, how do I make my first query.

Following on from that should be a tight section about what distinguishes URQL from other GraphQL clients.

Also, the title needs to change from 'urql Documentation' to something like 'URQL: Fast, Easy, Reliable GraphQL client', or whatever your tag line is.

[kitten]

We've discussed some options internally and I believe we have a couple of tasks for this:

• [x] Add a "Quick Start" guide to the docs and make it the index page
• [x] Move the current "Introduction" page to be "Overview"
• [ ] Add code snippets and up-to-date features to the homepage
• [ ] Add a "Comparison" page to the docs somewhere

All in all, the "Quick Start" guide should cover the most basic usage and also discuss the "Why someone would use urql" briefly as well as list some features, to enforce the homepage's message.

The homepage itself needs to simply be updated. The feature set isn't up-to-date and doesn't "sell" the library very well.

[jherr]

Happy to review any PR you have up for that. This is a great library.

[jherr]

Maybe a few more comments, having gone through the docs trying to understand exchanges.

• The wonka library is cool, but us as an end user of the library I'm not sure why I'm learning about it. I've written a working app that uses queries, mutations, and subscriptions, and I haven't used wonka at all. Can we take that information out? Or just make it a small sidebar?
• The exchanges information needs use cases for when and why I would alter them. For example, you might use an exchange to automatically add authentication, or something like that.
• There is a spelling error on the streams patterns page; framewrk should be framework.
• The Operations stream and results stream graphic could be made more operational by changing out the A, B, and C nodes with the default set of exchanges, then noting best practice places for extension. For example, here is where you would add an exchange to alter the payload before it goes to the client. Here is where you would add an exchange to alter the response from the client.
• The site could use an FAQ. Topics could include; How queries could be merged? How do I get started with SSR? That kind of thing

Sorry to just drop this all in here. Honestly trying to help out.

[jakubriedl]

Also awesome addition would be migration docs from Apollo to describe what is needed. The process is very straight forward so showing people how easy it is it could persuade them to switch. We personally hesitated for several weeks because of the migration unknowns and were pleasantly surprised how easy it was.

[wgolledge]

Great idea @jakubriedl!

[earksiinni]

Just wanted to weigh in with a counterpoint to @jherr about wonka. I agree that it's not immediately useful, but I found that kind of low-level information about architecture conceptually useful. I'm coming from Relay where the docs are frequently outdated/incomplete and much of the architecture is opaque (despite the presence of architecture docs on their site).

The fact that urql's docs go so deep into the streams architecture was a key reason why I decided to migrate from Relay. I read it cover to cover and came away with full confidence that there wouldn't be too many surprises because I understood the library's core. (And by the way, the illustrations are excellent.)

Perhaps if it's too distracting for some users, the wonka parts could be moved into another section rather than reduced to a sidebar? Personally, I like them just as they are, but I understand why others might not.

[kitten]

I'll have to close this for now, but I believe I'll reopen this once we have a concrete plan for the landing page, which I need to get internal design time for first 😅