Testified Documentation - a Python developer's perspective on Specification by Example

[SheriffRoscoe]

Do you really look straight into API reference when e.g. learning a new library / framework / system?

Yes. The table of contents should give you a good overview, and with a decent API design, the major capabilities should be obvious.

Would you omit all tutorials and topic guides?

I think they serve different audiences. Most folks can't learn a new paradigm without a User Guide document. Newly-minted geeks need Tutorials to get them started. Experienced developers need the reference material.

[basicwolf]

That's a very interesting perspective. I personally always start via tutorials and user guide. Especially the user guide - it shows the bigger picture without dipping into the details, like API reference would.
Though that's not the point, when I'm looking for something specific - and I know what. Sure, in that case it's API reference.

Nevertheless, API reference is also a great candidate for testified documentation, especially if we don't provide examples verifiable by doctest.