[docs] Questions about API documentation
Ahmet-Serdar Karakaya
selphiron at zedat.fu-berlin.de
Tue Mar 7 19:28:21 EST 2017
Hello,
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?
Regards
Ahmet-Serdar Karakaya
[1] https://docs.python.org/devguide/documenting.html
[2] http://docs.oracle.com/javase/8/docs/api/index.html
[3] http://perldoc.perl.org/
More information about the docs
mailing list