Questions about API documentation

[Steven D'Aprano]

On Tue, 07 Mar 2017 17:06:03 -0800, selphiron wrote:

> Hello,
> 
> I am trying to understand how to write good API documentation. 

Nice questions!

> 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
> conditions?

Both, I would say. Use short examples for simple things, and larger 
examples for more complex things.




-- 
Steve