Questions about API documentation

[dieter]

selphiron at gmail.com writes:
> I am trying to understand how to write good API documentation. I have read “7. Documenting Python” in the python developers guide [1] and skimmed the Doc-SIG email archives, but I still have some questions and I would appreciate your help. (Whenever I refer to me in the following questions, I mean documentation authors in general)

I fear that has much to do with preference -- both on the side
of the author as on the side of the user.

Personally, I prefer documentation of the following kind:

 * an overview document gives the grand picture (architecture, primary
   concepts, building blocks)

 * detail documentation is terse - based mainly on well chosen names
   with some additional information where this is necessary

 * if necessary, e.g. for a specific target audience, an additional
   document give usage/configuration examples

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

You go into details where a typical user would get at a loss without
the detail.

What is "typical" depends on your target audience.
It is more an experienced user when the target audience is
"senior developer" (e.g. for a module like "ctypes"); it is more a
beginner when the target audience is "occasional developer".

> 2) Should I give a code example for each method and object?

Only, if it is non trivial -- or in a separate document/part of the
documentation targeted at less experienced users.

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

My preferences would say: the first kind is likely unnecessary
altogether. The second kind may be good in non obvious cases.

> 4) The documentation of the Python Standard Library is quite verbose or like a book / tutorial. Some other documentations like JavaDoc [2] or PerlDoc [3] use a more reference-like documentation. Why did Python choose a different approach? Was this discussed before?

The Python library documentation is rather heterogenous in this respect --
likely because many different people with different preferences have
contributed.

> 5) Do you have any other advice? Are there things I should be aware of?

I should say that there is a big camp with completely different
preferences from mine. I mean the "doctest" camp.
It favours to combine documentation and testing and
advices to have executable docstrings covering all test cases.
This gives a very detailed documentation.

As you can imagine I do not like this advice and the resulting
documentation at all. From my point of view, the requirements
for good documentation (overview, compactness, concept based)
are quite different from those for testing (completeness)
and for me such documentation is difficult to read.