Questions about API documentation

selphiron at selphiron at
Tue Mar 7 20:06:03 EST 2017


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)

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.

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

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?

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?

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






More information about the Python-list mailing list