Pythondocs.info : collaborative Python documentation project

[Christoph Haas]

On Sunday 17 September 2006 04:31, Brad Allen wrote:
> Here is an idea for improving Python official documentation:
>
> Provide a tab-based interface for each entry, with the overview/summary
> at the top-level, with a row of tabs underneath:
>         1. Official documentation, with commentary posted at the bottom
> (ala Django documentation)
>         2. Examples wiki
>         3. Source code browser with a folding/docstring mode
>         4. Bugs/To-Do

I like your idea. The MySQL documentation site just came up to my mind. 
Users can write comments to articles there. And the documentation team can 
pick them up and include them in the official documentation. What annoys 
me most about the Python documentation is that it may be technically 
complete but a human being will never figure out how to solve the puzzle 
of 50 class methods without getting a proper example. It's like showing 
some non computer scientists a syntax diagram to get them started with 
something.

For today I plan to check out the SVN repository containing the official 
Python documentation and see how well I can contribute. But since many 
people are probably good Python programmers but less good in maintaining 
complex documentation structures (especially in LaTeX) it might help to 
allow more direct contributions. Ubuntu's Launchpad for example contains a 
component where anyone can help translate docstrings for Debian/Ubuntu 
packages. No more knowledge needed.

At least it doesn't appeal to me if Python's documentation team says "just 
open up a bug report on sourceforge - we will deal with the rest". Perhaps 
this is a decent approach considering the quality of contributions. I 
can't tell.

 Christoph