Navigating Shopify documentation is difficult: more !== better

vfonic commented 2 years ago

NOTE: There's some rant mixed with UX/DX issues in this issue. Feedback is a gift. Take it or leave it. Feel free to close this issue if you don't find any value in it.

Summary

I'm a long time Shopify developer (more than 5 years now). I've been around when Shopify had almost zero documentation on how to build Shopify apps.

Today we're looking at the renaissance in Shopify documentation, which is wonderful! I like the playful pixel art and the vast documentation available.

However...

Motivation

I noticed there's a new ShopifyAPI gem version (v10) and I wanted to be a good citizen and keep up with the latest Shopify developments, so I opted to install it.

It took me several minutes to find how I can initiate a Shopify session. I know about .with_shopify_session method and I'm glad to see it's still around. However, I wanted to be continuously "logged in" so that I don't have to wrap every line of code with .with_shopify_session while I'm trying things out in rails console. What I usually do is I create a new method in my Shop model called login and I just call shop.login and the session activates.

This would be truly magical to have something like this.

Instead, after reading a huge chunk of documentation and then finally finding the solution by reading the source code, this is one way I figured how I can get "permanent" session:

session = Shop.retrieve(shop.id)
ShopifyAPI::Customer.all(session:)

Describe alternatives you've considered

When compared to:

shop.login
ShopifyAPI::Customer.all

It seems like there are a few points of improvement in the API.

Or how was it before?

session = ShopifyAPI::Session.new(...)
ShopifyAPI::Session.activate_session(session)

That vs:

shop.login

Which of the two is easier API and provides better/simpler DX? If you don't like login, you can call it activate_session. But please provide something simpler than those two lines of code that I always have to look up because the API is too obfuscated for me to remember.

Shopify currently has ton of documentation, which is great! However, the documentation for ShopifyApp and ShopifyAPI gems is scattered all over the place, is incomplete, and it's very difficult to follow: missing items in CHANGELOG, missing upgrade steps, missing source code for companion packages (App Bridge NPM package), etc.

Additional context

It would be great if it didn't take me 20 minutes to figure out how to use ShopifyAPI v10 after been using ShopifyAPI gem for the past 5 years.

https://github.com/Shopify/shopify_api#breaking-change-notice-for-version-1000 It says "Call ShopifyAPI::Context.setup", but it doesn't offer any example
There's a documentation linked, so I went there: https://github.com/Shopify/shopify_api/blob/main/docs/getting_started.md#setup-shopify-context There is some documentation here, but there's still some documentation missing:
- host_name - why is this information now required? What if my app is served from two different domains? (I do have one such app for whatever reason)
- It would be great if keys representing the same concepts would be called the same across the board: api_secret vs api_secret_key, scope vs access_scopes (even worse, in one case it's singular, in another case it's plural)
- There are missing optional keys that are undocumented: user_agent_prefix, private_shop, logger - this wouldn't be an issue, but it is because ShopifyApp generator adds these keys to config/initializers/shopify_app.rb initializer which creates more confusion.
I've opened the session storage doc and I'm more confused than before: https://github.com/Shopify/shopify_api/blob/main/docs/usage/session_storage.md Do I need to implement this myself? This is documentation, not inheritance in the code. What's the issue of linking to ShopifyApp from the ShopifyAPI gem? https://github.com/shopify/shopify_api => no mention of ShopifyApp gem. Why? Let's check other popular gem that can be used with and without Rails:
- RSpec: https://github.com/rspec/rspec-metagem#also-see
- factory_bot https://github.com/thoughtbot/factory_bot
- Pry: https://github.com/pry/pry#use-pry-as-your-rails-console
- Delayed::Job https://github.com/collectiveidea/delayed_job/#installation
- RGeo: https://github.com/rgeo/rgeo#extensions All of these mention various (Rails) gems that were built on top of the base gem. Only ShopifyAPI never mentions ShopifyApp gem, which, I'd argue, majority of developers use together. ... Ok, I finally found ShopifyApp session repository documentation: https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/session-repository.md There's a mention of self.retrieve(id), inline. The above example (showing how to use the retrieved session / how to login) would be much easier to find with a glance and understand...if it was a code block vs inline code.
Next, I tried to add webhooks. So I went to ShopifyApp webhook documentation: https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/webhooks.md I know ShopifyApp has great support for webhooks out of the box so I'm looking forward to that...only to find out that there's no link to Shopify documentation on available topics. I can't remember is it orders/create or order/created or orders/created and now I'm again wasting time on something that should be...a part of webhook documentation. This, although right in the middle of the page, was easily missed (maybe it's just my bad in this case), because the highlighted words were GraphQL Admin API and REST Admin API, none of which I was looking for. I was looking for "list of webhook topics", not two sentences of text to read.

awd commented 2 years ago

Thank you for taking the time to write this out. There is an agreement among the users here that this gem + ShopifyAPI must be improved for better developer experience, and to raise the bar on the quality of the apps being built.

I've found reporting issues to the documentation team usually has good results when you do it directly from the docs site.

vfonic commented 2 years ago

Thanks for looking into this! Could you please point me to "the documentation team" or how I can report issues to them...or even better, could you forward this issue to them so that we don't have to play this ping-pong where I have to report the same issue 3 times because I reported it to the wrong team? There's nothing more demotivating for me to continue offering feedback than to be bounced around a huge corporation's internal teams.*

When you say "directly from the docs site", do you mean the mini-survey at the bottom of each page: Was this page helpful? Yes/No

Or how can I contact the documentation team directly from the docs site? For example from this webpage: https://shopify.dev/apps/webhooks

Thanks!

*I understand that in this case my feedback isn't as useful as it would be if I was reporting some bug with the exact repro steps, but the same applies in that case - after I am told that I need to report this bug to another team, I usually don't follow up. You can also consider this a part of good DX, a good developer customer support.

nelsonwittwer commented 2 years ago

Thank you for the feedback! I have sent this link to our documentation team and will work with them to improve the experience of getting started with this gem.

Shopify / shopify_app