Questions about API documentation
steve at pearwood.info
Wed Mar 8 02:37:35 EST 2017
On Tue, 07 Mar 2017 17:06:03 -0800, selphiron wrote:
> I am trying to understand how to write good API documentation.
> 1) How much should I (or a documentation author in general) go into
> detail? I don’t want to bore experienced users, but I don’t want to
> scare beginners away either.
It depends on who you are writing documentation for. If you're writing a
tutorial, you should go into less technical detail and more examples.
But generally I expect that the official documentation for a module or
library should be aimed at experienced developers, not beginners. No need
to babysit them and hold their hand through everything: you can assume
they are competent at Python, but not experienced with your library.
> 2) Should I give a code example for each method and object?
I believe that every function, class and method should have two lots of
documentation: the docstring, which is available for runtime
introspection (e.g. using help(obj) at the interactive interpreter) and
more extensive, detailed documentation for non-interactive use.
I try to include at least one simple example in the docstring of every
method and function. This is both documentation and testing.
To me, doctests do not need to be exhaustive: no need to show every
possible case or option. They are primarily documentation. But some
people, including the writer of the original doctest module for Python
Tim Peters, uses doctests as exhaustive unit tests.
Large, complex examples should go into the non-interactive docs (when
needed). Simple examples should go into docstrings, but not necessarily
into the regular documentation: it depends on *how* simple. For example,
having demonstrated how x += 1 works in the docs, I probably wouldn't
bother to do the same for x -= 1.
But that's a judgment call and I don't expect everyone will agree.
> 3) I recognize 2 different kinds of examples: Some are rather small and
> right under the object or method description and some are quite long and
> at the end of a module in a use case. Which kind is encouraged at which
Both, I would say. Use short examples for simple things, and larger
examples for more complex things.
More information about the Python-list