API Documentation: What Can We Do To Make It Better

[Jessica Bredschneider]

Hi Shopify Developers!

My name is Jessica Bredschneider and I have been given the privilege of working on the API documentation over the next little while.

I have a background in Communications and a very small background in web programming (nothing compared to many of you, I am sure).

I would like to take your feedback into consideration while I am working on the API documentation.

So, if you have any suggestions for what needs to be added/edited/improved within the API documentation, feel free to post to this thread.

Looking forward to reading your suggestions.

[Denis Somar]

Hi Jessica,

A super basic set of instructions that goes from blank text editor to mini-app that uses the API would be really instructive.  (I'm a PHP guy so if it was done with PHP, that'd be even better, but beggers can't be choosers)

;-)

Denis

[Travis Haynes]

If you want a model to work off of, I am personally very impressed with Stripe's API documentation: https://stripe.com/docs/api

You can see how every single field is described in detail. That's something that the Shopify API documentation lacks. For example, if you look at a Product, very little of it is actually documented. It gives you very prolix JSON examples, but that's pretty much all that's there. For example, if I look at a product's variants, I see the "fullfillment_service" field, which is set to "manual" in all 51 instances that it appears on the page, with absolutely no documentation describing its available values, or even what it does, or how it works.

On the other hand, if you look at the Stripe API, here: https://stripe.com/docs/api?lang=php#plan_object - You can see that every single parameter is described in detail. It says if it's required, and what it does, the default values, and how to use it.

That's what I'd like to see: Balanced coverage of the API, free of prolixity, with more verbose descriptions, and clean, concise examples.

Thanks!

--
 
 
 

[Jessica Bredschneider]

Hi Travis,

Stripe's API looks like a great resource.

Thanks for directing me to it.

[Brian Getting]

Mailchimps API docs are a good example as well.

[Dave]

I am impressed. Using the words prolixity, verbose, clean, concise in one sentence.  

[Edward Ocampo-Gooding]

Dave: don’t be a jerk.

--
 
 
 

[Dave]

Edward. I was seriously impressed. To pull that off... you need to know the word prolixity, which I found out means too wordy. I connected that with not being verbose, with being clean, and with being concise. Travis pulled it off and for that I noted that I was impressed. Impressed. Seriously...  

Now Edward, you on the other hand, jumped down my throat here, insinuating I am a "Jerk" for using the word impressed. I suppose you could interpret my use of the word impressed as sarcastic but I resent that. Do I need to issue a disclaimer when I am being sarcastic? I sure hope not, that would be a true chore. 

Color me impressed please. 

Again... I was impressed. OK?.

Thanks!

loving Prolixity... ya!

[Edward Ocampo-Gooding]

My bad. Carry on :)

--
 
 
 

[Jimbo]

I'm going to agree with Travis: "It says if it's required, and what it does, the default values, and how to use it."

It's a real chore to be constantly crashing your program(s) in order to find out how relatively simple operations and assumptions don't work. It doesn't matter what the language is (and I actively program in five of them because of the kinds of customers we have).

The current API documentation for Shopify is long on content, but short on concept transfer in detail (which is the primary point of API doco).

Frankly, it's conceptually similar to learning a new human language by a dictionary... rather than a phrasebook. The number of words are plentiful. But I would need the minima of pertinent (and functioning!) construction examples to be able to quickly assimilate the pattern and syntax.

I can appreciate that the documentation authors may be intimately familiar with the resource. But they should consider that most of us might come to the API as strangers in a strange land.

JS

[Jessica Bredschneider]

Great feedback everyone! Keep it coming.

I was just curious how many of you know about and/or use the tutorials that are available? If you used them, did you find them succinct? Did they answer your questions?