Though the Portland sun is shining less these days, I’m still making the most of my coffee shop patio.

Indoors I’d be wearing a mask, but that’s better than things were a year ago: Long lines down the block, six feet apart, ordering at the doorway. You may remember I shared a story about my lack of empathy for someone who didn’t know what to order (after 10- 15 minutes of waiting in line).

The options at a coffee shop are not complex: Drip, espresso, or tea. Then choose a style, a size, and some optional modifications.

Though simple choices, it’s notable that every coffee shop menu provides some pre-arranged drink options.

You’ll never see a coffee menu like this:

You don’t need to choose your beans separately from your water from your consumption device. You don’t need to tell the barista to grind the beans.

It would be silly to expect you to list out the ingredients for your drink… especially if you haven’t had caffeine yet.

So, why do most API docs look like this?

A reference is important, but it’s an unlikely starting place for developers who need to understand why an API matters.

You can’t see this from what is essentially a list of ingredients.

Use cases, sample apps, and the humble getting started tutorial are far more effective for initial usage.

And yet…

The API reference is the classic first piece of documentation.

What if we adopted an Amazonian principle of working backwards? Before Amazon creates a new product, they imagine the press release. Well, they don’t just imagine it, they write it. It becomes the beacon for the work to build the product.

Try writing a getting started tutorial for a developer product that is not complete. Perhaps that might inform how it is built.

The worst case is you know a developer would never have to look through a list of ingredients just to figure out how they can be combined.

(Got a coffee menu that needs a fresh set of eyes? Our well-caffeinated team may be able to help)