[Python-Dev] 2.5 open issues
"Martin v. Löwis"
martin at v.loewis.de
Fri Apr 28 17:27:44 CEST 2006
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:
> This could be completed and committed into SVN soon.
Looks good to me.
More information about the Python-Dev