On Thu, Oct 6, 2011 at 6:47 AM, Jonathan Lange <j...@mumak.net> wrote: > On Wed, Oct 5, 2011 at 5:13 PM, Julian Edwards > <julian.edwa...@canonical.com> wrote: >> On Wednesday 05 October 2011 10:34:24 Julian Edwards wrote: > ... >>> I am happy to collate opinions on this and drive it forwards. >> >> I'm pretty sure you guys are more opinionated than this. C'mon, let us have >> it >> :) >> > > * As a rule, I favour in-tree docs with a web presence
+1 > * rST is the least bad markup I know of Absolutely. > * I hear from those in the know that "Manuel" is one way to get > readable, testable documentation (avoiding the "forced narratives" > that Gavin talks about). I haven't used it, but it's perhaps worth an > experiment The Manuel docs are rendered by Sphinx and tested with Manuel: http://packages.python.org/manuel/. The docs are pretty reasonable as documentation and they're also well tested. Compare the Sphinx-formatted output (above) with the source: http://packages.python.org/manuel/_sources/index.txt > * One of the key places that LP is missing docs is in __init__ files > and at the top of modules. I think these are often much better places > for general introductory documentation than in text files living in > other locations. Yep; We need more localized documentation near the code that it describes. Also, we shouldn't be afraid of writing more detailed conceptual documentation inline (in functions/methods). Documentation that allows developers to quickly ingest the base concepts required to understand a module/package/subsystem would be helpful. > * I really wonder how much text file documentation is needed? API > documentation (ala pydoctor) is often way more helpful for me for > understanding code, and good '--help' is better for understanding > tools. It's good to think carefully before adding guide / howto style > documentation. Less is more. I have never gotten much out of API documentation, especially generated API documentation. I can read the code about as quickly as I can read API docs and reading code makes it easier to drill down into the contents of a function/method when the need arises. -- Benji York _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : launchpad-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
