[Python-Dev] 2.5 open issues (original) (raw)

"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:

http://starship.python.net/crew/theller/manual/manual.html This could be completed and committed into SVN soon.

Looks good to me.

Martin

More information about the Python-Dev mailing list