These are great thoughts. One comment below... On Tuesday, January 18, 2011 7:21:05 PM UTC-5, cjrh wrote:
> I think I am in favour of your suggestion of putting references to > source units inside the book itself. I would probably suggest that > the format of that inclusion be little more than a list of applicable > source files per section, rather than the level of additional detail > you demonstrate. To add further discussion would create more > maintenance work for the documentation, and would detract, I feel, > from the purpose (and quality, assuming no duplication) of the API > documentation. Epydoc provides a space for writing module-level > comments, and my gut feel is that the higher-level description of the > source code itself should appear here. Perhaps a link from the book > chapter to the Epydoc page for that module? I don't have a strong opinion on where it should live, but I don't want to discourage the kind of explanation Jonathan has provided in his example. It's helpful to get a higher-level view of how the system really works, and that may not always be as easy to gleen from module/class/function docstrings. For example, Jonathan's "Installation and Deployment" section refers to more than one module, so that kind of thing needs to be handled at a higher level than just a module docstring. He also explains installation and startup scripts, which are probably not covered in the API documentation at all. So, yes, we should put as much as we can in the docstrings, but there may still be some room for additional guidance and explanation. Of course, it would be great if we can get it all into a single interface (i.e., the Epydoc interface, or some alternative if Epydoc isn't flexible enough for the additional material we might want to add -- some other options are listed here: http://wiki.python.org/moin/DocumentationTools). Anthony
