Documentation & Practical Code Examples

[tom2strobl]

Let me start off by a claim: urql is one of the best libraries that is being slept on. It is thoroughly thought through (oh hey, a triple thou). I'm fully aware of the desired modular nature (which is a good thing!) and that this naturally makes things less practical and more theoretical, but I truly think the current state of documentation hinders a lot of urqls deserved success.

The documentation is super theoretical and it read more like a dissertation than a bridge to get someone started. I had to read every word on ever page at least three times to just even really get started and now after ~2 weeks I still feel like I'm doing things not 100% correctly.

In my opinion, the best way to get people hooked is to a) get someone interested by showing off the USPs and what it is able to achieve, then b) showing concrete, short examples to give a taste of how code using it looks like (kinda like what you have sprinkled right now in the docs), then c) concrete examples for lets say 75% most common use cases (to learn from, to understand by practicality why things have to be a certain way and to get started more quickly) and then last but not least d) theorycrafting, reasoning behind architecture, a look under the hood and tips on how to solve more complex and specific use cases.

I feel like currently we have a little a) which is ok, then huge amounts of d) with a little b) here and there, but no c) at all. Afaik there is not a single concrete example of showing eg. a simple todo-CRUD with optimistic responses as a full, connected example. At least not in the documentation if I'm not mistaken. Or in other words: there's very little code to look at that shows you "how composing everything is supposed to be done correctly". It's also a lot easier to understand the whole architecture that is described in words when there is a practical fully composed example to follow along, eg. the most complex case with normalized cache, optimistic updates and offline

I really don't want this to come off as a rant, but more as an incentive, because again, I feel like its a great piece of software that deserves more recognition. 🙂

As much as I think AWS Amplify is horrible and definitely not-production-ready, I think they have some good examples of Documentation (mapped to the points a-d above).
– a) After this I have a broad overview what I can do https://docs.amplify.aws/cli/graphql-transformer/overview
– b) After this I know how I can do things https://docs.amplify.aws/cli/graphql-transformer/connection
– c1) Now I see how it's done in practice https://docs.amplify.aws/cli/graphql-transformer/examples
– c2) Now I understand and can follow along a full, complex example https://docs.amplify.aws/cli/graphql-transformer/dataaccess
– d) Theorycrafting/Under-the-hood is something they lack, but we don't have a shortage of that in urql, so no example necessary

What are your thoughts on this?

PS: you cant open links in a new tab in the current docs due to a relative URL issue

[kitten]

(btw: I'm currently fixing the static builds of the docs sites coincidentally)

I wholeheartedly agree. As we've worked on the docs we wanted to convey the theory and architecture strongly and I've worked on that over the last week, compressing content, removing an overwhelming amount of theoretical explanations and restructuring some parts. From my point of view (re: d) the theoretical explanations for urql, it's core, and Graphcache are pretty solid now, but only offer enough information if a reader is engaged, understands what they're about to read, and read the entire thing. This is really suboptimal.

We found it pretty hard to sprinkle a lot of examples throughout the documentation. I believe the new Graphcache pages for "Local Resolvers" and "Cache Updates" do a better job at this now.

Nonetheless this obviously doesn't solve the lack of two things I have on my radar;

• There should be large amounts of practical examples for each use-case isolated to what someone is looking for (Next's examples are a good & ideal sample of what this may look like.
• There should be one usage guide that explains how to set up an application from scratch so that people don't get lost when switching to the normalised cache.

The latter has turned out to be hard because we don't have any opinionated structures baked into the library. That's why the "Urql Framework" roadmap exists. Once that's done it gives us a good path to make practical recommendations for a guide.

The problem with the former is that it's quite hard to actually build solid examples that are easy to run. We've experimented with service worker APIs so that the examples would "just work" in CodeSandbox, but those are cumbersome. We also tried to get some example APIs deployed somewhere after, but we didn't get very far with that since we have a large amount of edge cases to represent.

I appreciate the advise and would love to collect some ideas on how we could address this quickly! 💙🙌

[tom2strobl]

Yeah, next typically does a good job at these, but one has to admit that explaining a <Link> Component is a lot easier than a normalized Graphcache :-)

I see your point about the scale. As a first step it probably makes sense to skip any UI specifics and boilerplating, I personally struggle almost exclusively with updates, optimistic & resolvers, so as a starting point showing best practice cacheExchanges for eg. a Blogpost/Authors situation with the corresponding graphql queries/mutations is probably all that I'd need. That's probably something you can even display within one file/snippet.

It would also be pretty cool if the community would chime in some of their solutions to their usecases. Eg. soft-deletes (eg. setting a deletedAt field instead of actual deletion)