launchpad-dev team mailing list archive

[Benji York <benji.york@xxxxxxxxxxxxx>]

On Thu, Oct 6, 2011 at 6:47 AM, Jonathan Lange <jml@xxxxxxxxx> wrote:
> 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

+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