Example query using each directive maybe?

[hailwood]

Hey @chrissm79 ,

New docs are A+

Was thinking maybe we could add an example query using each directive to give the users a clearer understanding of how applying it manipulates the query.

Thoughts?

[chrissm79]

Hey @hailwood thanks for the feedback!!! The docs could certainly benefit from a "examples" section, I was thinking at the bottom of every page using several directives per query/mutation so the page doesn't get too overloaded. But yes, they could absolutely benefit from more clarity!! I was also planning on working in a "How Do I" or "FAQs" section that would be similar to the questions you presented on the main repo.

Let me know if you have any other feedback/questions and I'll update this post when I get some more content worked into the docs!

Thanks @hailwood!

[spawnia]

Hey @hailwood

Nice idea. However, i am struggling a bit how to do example queries specific to directives. Since the directives are server side...

Also, most of the directives are pretty substantial in what they do, meaning they do enable a specific purpose. So there is not really a before and after.

The "How To's" seems like a great approach. A set of common problems and a suggestion for how it can be solved with Lighthouse.

[spawnia]

Starting from v2.2, all directives live on one page. Comprehensive guides are there to explain certain use-cases and logically group directives according to their purpose.

I think some directives may benefit from example queries, for others it seems a bit over the top.

[hailwood]

@spawnia I unfortunately don't have time myself currently ⏳,
But I was thinking we could transfer those "How would I..." questions to the docs as you've suggested (and was actually their original intent), And then on the directive page under relevant directives have

Example Usage:

• How would I x
• How would I y

Then it links it all together quite nicely, and it seems natural that the directives that need their usage explained probably need a scenario around their usage.

Thoughts?

[spawnia]

Definitely working on transferring the "How would I" issue over to the docs. I am still not quite sure about how much info should go on the directives listing, apart from the basic information and api. Cross-referencing with use-cases might be a great way to make the information easily discoverable while keeping things DRY.

[spawnia]

The new guides/directive structure is well into the making. I tried to add examples where they make sense.

I guess we can close this Issue, as we can all agree this is a good idea and we will have to continually work on this case-by-case.

[spawnia]

The guides in the new docs have lots of example queries. @hailwood feel free to add more where you feel they are missing. Closing this for now.