[Python-Dev] 2.5 open issues

["Martin v. Löwis"]

Thomas Heller wrote:
> I was fearing it is getting too long.  How many pages do you expect
> or will you tolerate (yes, this is a serious question)?

I don't think there should be a page limit to documentation. If it is
structured into sections, then size simply doesn't matter on the Web:
people can easily skip over it / ignore it if they want to. It only
matters for the size of the distribution, but only slightly so: I doubt
it contributes significantly to the size of the whole distribution.

> 2. A reference manual, listing all the available functions and types
> (it will probably duplicate a lot of what is in the tutorial).

I would feel that this is a must-have document, and completeness is
certainly a goal here. Now, if certain parts are still undocumented,
I wouldn't make creation of this documentation a release requirement,
but text that already exists should be included.

> 3. Some articles/howtos which cover advanced issues.

I don't think they are necessary; if Andrew thinks the howto
section would be a good place, I don't mind.

> I have the start of a reference manual, which is about 12 pages now.
> Incomplete, some sections are not yet or no longer correct, but you
> can take a look at it here:
> 
> http://starship.python.net/crew/theller/manual/manual.html
> 
> This could be completed and committed into SVN soon.

Looks good to me.

Martin