On 9/17/06, A.M. Kuchling <[EMAIL PROTECTED]> wrote: > On Sun, 17 Sep 2006 18:10:51 +0200, > Daniel Nogradi <[EMAIL PROTECTED]> 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. -- http://mail.python.org/mailman/listinfo/python-list
