What people said were the common mistakes organisations make with their API documentation

Here are the responses we received when we asked, what are were the common mistakes organisations make with their API documentation:

Thinking the auto-generated API reference is sufficient documentation.

Shauna

Too many docs, not enough code samples.

Laura L.

Too many “hello world” code samples; Not enough that accomplish something useful.

Scott S.

Not seeing API doc as a part of the *consuming* developer’s whole experience. API has to be well-designed, doc done well, and those aren’t the only successful parts of DX.

Emmelyn

Code examples that don’t work or are out of date are most frustrating to me.

David B.

Not selecting a suitable level of automatic docs generation for reference material (init options, methods, events) from the source code.

Ed D.

I think the navigation/structure plays a big part in API documentation, often it is difficult to find what you are looking for which puts you off using the help all together.

Sarwat

Some errors I’ve seen (and also probably committed):

• treating them as static, one time projects (usually due to resource limitations)
• Code samples that don’t work because:
  • they never did
  • they were not maintained with the rest of the systems that use them
  • they are too complicated (but that can also be a problem with the API design)
  • they are too simple and show the obvious (but, hey, they can say they have a code sample, right?!)
• No value proposition. Like we’re supposed to know instinctively what problems an API solves
• Unrecognizable use cases – solving problems no one has (or knows the have)
• Creates a new terminology and taxonomy for an existing domain
• Involves the doc writer/team too late
• Involves the doc writer/team too soon (better than too late, but can be troublesome, at times)
• Keeps the code secret from the writers (but still expects world-class documentation and examples. Yes, that really happened)

Bob W.

In my case, I was presented with a nebulous argument along the lines of “If you don’t know the value of an API, you wouldn’t be using it.” I bristled in response, predictably.

Dallas

Monolithicism – that is, employing a WORD to PDF (like) documentation model.

Joe D.