[Python-checkins] r70438 - python/trunk/Doc/library/functions.rst

["Martin v. Löwis"]

> On a separate topic, we also need to make an effort to look
> at all of the big/loud caveat/warning blocks to make sure they
> are really necessary.  No other language docs advertise themselves as
> being full of minefields.  Look at the main Java
> docs for comparison.  They are shot and sweet and say what
> a function does, period.

I hear frequent complaints that this style of documentation is unusable
to casual users. They don't want a specification of an API; they want to
know how to use it. And they don't want to filter that out of the
tutorial, but they want to see how to use it when they read the API.
So examples *must* go along with the specification.

If you would have to perform some navigation action to find them - that
should be ok. But you must not need to search for examples.

Notice that examples are not necessarily tutorials. Tutorials are
designed to teach the reader some skill, by sequentially confronting
him with new facts. OTOH, examples in API documentation often serve
as specification-by-example, i.e. allow the user to skip the
plain-english specification, and build a mental model for the API just
by reading the example.

Regards,
Martin