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 * Discoverability and navigation is key. One problem with many of our in-tree-which-are-doctests is that you have to know where to look. * rST is the least bad markup I know of * It *is* easier to JFDI with a wiki * 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 * 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. * 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. * Wikkid seems nice but is not there yet. Needs a lot of work. jml _______________________________________________ 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
