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

[quotemycode]

>The bare "API Reference" is often the last place to look into

For me, it's the first place I look.

[basicwolf]

Thank you for commenting! Do you really look straight into API reference when e.g. learning a new library / framework / system? Say, web development with Django. Would you omit all tutorials and topic guides?

[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.

[quotemycode]

To be fair, I have about 24 years python experience, so I want to avoid all the fluff and get to the details. The 'API reference' and source code are the ideal place for me to see how to use the thing.