It can be hard to find references on options

[LinusU]

Hello,

I had a slightly negative experience using your docs today, and my feeling is that this specific thing is somewhat recurring here. Specifically in this case I wanted to find the reference on what I can pass in as errorPolicy, and what the different modes does.

This is the part that I wanted to find:

Unfortunately, searching for errorPolicy did not yield this result at all. Instead I get three other options:

The first one is actually really close, but it takes me further down on the page, so I didn't realise that I could scroll up to find more information. It takes me to a quick explanation that one can set an errorPolicy to e.g. useQuery and than shows an example of using 'all'.

The second hit takes me to a page that again tells me that "If you set errorPolicy to all, useQuery does not discard query response data", but doesn't list all the available options. It ends with "For more information, see Handling operation errors", and a link to the top of the page of the first hit that explains about the different errors and error handling in general. I still did not realise that this page actually had a list of the available options.

The third hit looks really promising, it takes me straight to the heading options.errorPolicy and lists the three available values along with a description for each. Success! But wait... This page is actually called "HOC (deprecated)" and is not the list that I'm looking for, even though it seems that currently the valid options are the same.

---

My personal style of developing often leads me to just wanting to see references and definitions, whilst I fell that the Apollo docs are much more guide/examples oriented. This is probably a good thing, since I think that many people prefers it that way! It would be amazing if we could make some tweaks to improve the docs for people looking for references.

A suggestion that I have would be that if I search for an exact match of an option or function name, there would be some way to jump to the reference of that option/function. Maybe even a part of the documentation that focuses on just references and no examples.

---

Another example is searching for useQuery:

The first hit is how to use TypeScript together with useQuery, and doesn't list or link to the available options that I can pass to useQuery.

The second hit takes me to a list of the options, I then scroll down a bit to errorPolicy:

There is not a list of the available options here, so I click the "see GraphQL error policies" link:

This starts of with an example of how the response from the server looks, and then finally when I scroll down I can find the valid options!

---

For a "reference first" person this is quite frustrating to navigate, and I would love if there is something we could to improve this situation! 🚀