An API a Day - my new blog about API and programmer docs


#1

My new blog:
anapiaday.tumblr.com

Some more-established blogs in the same vein that I enjoy:

ffeathers.wordpress.com

idratherbewriting.com

And, of course, for all things related to APIs, I strongly suggest
ProgrammableWeb.com


#2

I’m finally reaching a place where I can start to think about structure and content for an API guide we desperately need. Thanks for sharing – this was helpful for me.

Another link I’ve found helpful is: http://blog.parse.com/learn/engineering/designing-great-api-docs/


#3

Thanks - I enjoyed reading the Parse article too.


#4

This is so great, thanks for sharing! I actually profile APIs as a Directory Researcher for Programmable Web, and I can tell you what a joy it is when I come across an API with great docs. Conversely, it is really frustrating to encounter APIs that look really cool, but have little to no documentation. As the Parse article states, “Who cares if your product is the most powerful thing in the world if no one understands how to use it.” (!!) True facts.


#5

ProgrammableWeb is just about my favorite site at the moment!


#7

+1 for ProgrammableWeb!


#8

Thanks, this is helpful for me.


#9

Ashley, you mentioned that you’re a Directory Researcher for Programmable Web. One question I’ve been interested in is how helpful interactive API consoles are to developer writers. To be more specific, in some API doc, there’s a feature that lets developers try out calls (e.g., this is one of the main features of Swagger). Has there been any research as to whether developers find these try-it-out API console / interactive explorer type features beneficial? Or are they just a novelty in the documentation?


#10

Hi Tom!

Sorry about the delayed reply. I’m not sure how well I can speak to your question. I’m not a developer myself so I don’t utilize that feature of the docs. However, I always make sure to mention when an API console is included when I write up an API. I’d be curious myself to learn what types of documentation developers find most helpful. The style and depth of API docs seems to vary incredibly. It could be a good project for someone at ProgrammableWeb to write on though, I should pass it on!


#11

@tomjohnson1492: This showed up in my twitters today, although the basis for the claim is, ah, unclear:

My sense, based on a statistically insignificant dataset, is that yes, developers don’t want to read, they want to copy and paste (or just import a client library). But “play with the API” in the way that you can with swagger-ui or other sandboxes/consoles – I’m not so sure. I know that internally for one project I worked on, we wound up with swagger-ui running against a few endpoints/resources, but nobody ever really did anything with it, and ultimately it was abandoned.

There’s a lot more to discuss – and certainly as @Ashley says, there’s a huge variety in (REST) API docs. For lots o’ reasons …


#12

I think that it’s incomplete to say “devs don’t want to read.”

I think it’s more accurate to say that “devs want to be as productive as they can, as quickly as they can.” If they need to read to be productive, they will. If copy/pasting code will make them productive, they’ll do that. If playing with a swagger interface will make them productive, that’s what they’ll do. If they could download what they need to know into their head from a USB stick, they’d do that.

The challenge for devs is to be able to assess correctly which model will get them to where they want to be (i.e. done) as quickly as possible. When devs are our audience, their challenge is our challenge as technical/programmer writers. So, the right answer is what your devs need to be productive with your product.

This makes the problem very interesting and challenging (as most interesting problems are) and, unfortunately, not a problem that lends itself to a one-size-fits-all solution.


#13

Interesting and challenging indeed. I think is it very important to remember that there is no way to “solve” communication problems. Every reader has a different background and is trying, based on incomplete information and understanding, to complete a specific task efficiently. Information foraging theory, as well as John Carroll’s experiments outlined in “The Nurnberg Funnel” tell us that they will essentially forage for a solution while minimizing their expenditure of mental energy.

The solution they arrive at may be for from optimal, because it is actually based on optimizing the expenditure of mental energy in finding a solution, not on optimizing the solution itself. The reader cannot predict the research path that will lead to an optimal solution so they forage, going back and forth between trying stuff and seeking new snippets of information.

We cannot, therefore, create a straight path for all our readers to follow. At best, we can create an information field that is easier for them to forage through.

I’ve blogged about this a number of times, notably here: http://everypageispageone.com/2014/06/24/the-readers-path-cannot-be-made-straight/

On the practical information design consequences: http://everypageispageone.com/2015/02/02/you-cant-size-topics-for-specific-information-needs/

Mark