Here comes the big shock, API docs are often not enough. Whilst they describe what your product does, they don’t always describe what someone is trying to acheive and assemble
A documentation crash course
Chris Chinchilla
704

I enjoyed the whole article, but this point in particular struck something on me.

It can be very frustrating to find a medium-sized (or greater) project that only provides API docs, because the terms and concepts tend to only make sense in the context of the library, so end up resorting to one of the following:

  • You invest a lot of time playing with the library and maybe reading unnecessary parts of the docs trying to get a handle of it.
  • You read the tests (if any) trying to figure out how to do stuff.
  • You look up for tutorials on that project in particular.

This is in contrast with great documentation examples. Python documentation for example, has sections dedicated to tutorials and more in-depth explanations (there are doc logging API and both a basic and an advanced tutorial on logging).

Thanks for the article! I feel this is an underdiscussed topic that deserves more attention.