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 -- http://mail.python.org/mailman/listinfo/python-list