Pythondocs.info : collaborative Python documentation project

[Calvin Spealman]

On 9/17/06, A.M. Kuchling <amk at amk.ca> wrote:
> On Sun, 17 Sep 2006 18:10:51 +0200,
>         Daniel Nogradi <nogradi at gmail.com> wrote:
> > start a new one. What would be very useful though is more visible
> > links on the python.org site to the activestate repository where
> > appropriate. I'm not sure the pyhon.org people would want to promote
> > activestate though, nevertheless it would be a great help to many.
>
> There's no reason not to link to ActiveState... but are there RSS
> feeds or some similar mechanism to get all the recipes for a
> particular module?
>
> Fredrik Lundh also proposed a way to publish examples that get linked
> from the documentation <http://effbot.org/zone/idea-seealso.htm>, and
> there's some code in the Python sandbox for incorporating links
> (sandbox/seealso).
>
> However, this code isn't used at the moment because I have no idea
> what to do about version controlling the links.  Do we just use the
> current links whenever the HTML is generated?  Make a copy of the list
> and commit them into SVN, so the links cease to be updated but are
> consistent for a given version's docs?  It would be nice to figure out
> what to do.
>
> --amk

I think that, clearly, a combination of community and automation to
gather the best information from around the tubes is a good thing to
be explored further. However, without careful editing and eventual
integration into the official documentation, the information will just
stagnate under the rug.

Beyond just getting more information into the documentation, which
already covers everything if you know where to look, we need to
seriously take a look at how newcomers are thinking about the problems
they have and where they expect to find the answers. Perhaps some
rearranging of the documentation is in order, or some cross-references
to be added. These aspiring pythoners are asking "How do I do X?" and
there is no clear path to many of their answers without knowing the
answer yourself. That is the problem, more than any lack of examples
or clarity in the text.

How can we solve this? We need a two fold approach to improving the
documentation. We need to increase community support of the official
documentation, perhaps with forums/wikis attached to different parts
of the documentation for the dropping of examples, links, and
suggestions, along with discussion on how to further improve them. Add
a form (built into the wiki?) right there with the docs where people
can submit additions, corrections, expansions, and other changes to
request.