launchpad-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxxxxxx>]

On Thu, Feb 11, 2010 at 7:37 AM, Bjorn Tillenius <bjorn@xxxxxxxxxxxxx> wrote:
> On Wed, Feb 10, 2010 at 09:17:36PM +0000, Gavin Panella wrote:
>> Long doctests can accumulate large amounts of state. Object, test data
>> and variable reuse causes headaches for developers and reviewers. This
>> bothers me, so I brought it up at a reviewer's meeting a long long
>> time ago:
>>
>>   "Because of the accumulation of state in doctests I think it would
>>    be good to limit new doctests to 200 lines or less. gmb wrote a new
>>    doctest last week of just under 200 lines and it was still
>>    perfectly comprehensible. That's where the number comes from."
>>
...
> This is the basic idea that I'm going to experiment with first. It might
> turn out it's not feasible. For example, good documentation is hard to
> write, and it's only feasible to write good documentation if someone
> actually reads it. So another challenge will be to actually make use of
> the documentation, providing in a way that people will find it useful,
> and actually read it. The less useful documentation proves to be, the
> less we should spend time writing it.
>

Great stuff.

I'm sure Matt can help with this more than I, but there absolutely
must be a clear audience for every document. Ideally, each doc should
have a goal (e.g. "... you'll understand how the codehosting server
works") and some prerequisites (e.g. "You won't understand this unless
you already know SSH. Read RFC 2xxx").

Getting clear on these, then getting clear on navigation and
ease-of-access sound like great ideas to me.

jml