I knew something was up when my Bookmark for Shopify GraphQL documentation changed and was 404. When I re-found the documentation, it was all there alright, but totally new. Totally different.
And now I cannot find anything! Nothing makes sense! It used to be easy. Queries. Mutations. Now it is just a huge hodgepodge list. What happened to careful deliberation and asking the people who EAT YOUR DOGFOOD what they think? Did anyone at Shopify think to maybe ask us with some BETA offerings, if we'd like this or not or if we found it useful or not.
I get it. GraphQL is tough to document because basically it is just COMPUTER CODE for documentation, and therefore no humans intervene much, but this is sad. Sad because GraphQL is wee bit of a joke in terms of code (snake case camel case random crap case anyone)... so ya..
Please. Make an effort to help your developer community out here. These new docs will eventually work I suppose, but right now... worth a RANT. Rant over. Nice try... C in university documentation class from the Prof.
Like @HunkyBill I am not a huge fan of categorising API documentation by intent or some "virtual for humans grouping" as is now.
Luckily schema introspection and self-documenting nature of GraphQL are all we really need IMO.
I beg to differ. I would not sell short the concept of examples and through them, the presentation of philosophy. We have been left drifting or spinning in the wind. By this I exactly mean:
- multi-location fulfillment operations are barely comprehensible, lacking any direction vis-a-vis, here is a store setup with locations, here are the products setup and here are some orders with said products, fulfilled these ways.
- product publishing remains murky at best
- how to use best update products now that we have Media, Images, and endpoints for both, even though Images are Media, and WTF is going on there?
And that list is certainly puny as I have better things to do than spend hours documenting my frustrations.
I am not stupid and I spend a lot of time experimenting to see what might work, but often I am left wondering why things don't, and even why they do! I get it, you cannot abandon code you left us to use 2, 3 or more years ago, so now you are pushing out all new codes, supporting old codes, and thus confusing the heck out of us. Littering a little "deprecated" notice is no help. You have to be backwards compatible WHY? To not hurt feelings? I have had to do enough scrambling over the years to keep up with the Joneses, but in this case, the GQL docs have just not been really approachable, ever.
So what I am pointing out, is that while it is certainly possible to write code that works, this new documentation system is not an improvement, and we in the community are shocked there is such little effort being expended to show us the ways in which we can enrich the system with our contributions. The story being preached continues to be we love you, but the reality is, the stories are machine generated, and they show no love.