selphi...@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. -- https://mail.python.org/mailman/listinfo/python-list
