launchpad-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxx>]

On Wed, Oct 5, 2011 at 5:13 PM, Julian Edwards
<julian.edwards@xxxxxxxxxxxxx> 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