On 08/12/2009 12:27 PM, Raymond Hettinger wrote: > On Aug 12, 3:32 am, Paul Boddie<p...@boddie.org.uk> wrote: >> Maybe the problem is that although everyone welcomes contributions and >> changes (or says that they do), the mechanisms remain largely beyond >> criticism. > > FWIW, I support the idea the regular docs incorporating links to > freely editable wiki pages. That will at least make it easier for > people to make changes or add notes. > > That being said, I would like to add a few thoughts about the > current process. ISTM that important corrections (when the > docs are clearly in error) tend to get made right away. What > is more interesting are the doc requests that get rejected > and why:
[...snip interesting categorization of "bad" doc enhancement suggestions...] > In short, most doc requests that get rejected are requests that didn't > actually improve the documentation. > > I do support links from the regular docs to an external wiki but the > main docs should continue to go through the regular process using the > tracker. What is the purpose of such a wiki? 1. To provide hopefully useful adjunct information for each doc page? 2. To provide a source of input for improving the next version of the docs? In general I have a low opinion of wikis. Nearly all the ones I've seen are trash heaps of out-dated and wrong information, atrocious writing, and comments that look like the middle of some arcane usenet thread. They lack organization making it very difficult to find the needles of good information in the haystack of junk. The only one that seems to work is Wikipedia and it "works" because it has a very heavy-weight process controlling contributions. (And even then, my biggest complaint with Wikipedia is the poor writing quality in a lot of articles.) I'm not trying to be negative, only pointing out that to serve either of the goals I asked about above, a wiki will probably require a considerable management effort that should be faced up front. To simply set up a wiki and "wait for it to self-organize" (as I here read once) is a pipe-dream. How will it be managed? Anything written stays? If not what standards are used to remove junk entries? Wrong entries? Questionable entries? Who will do this? Will they act based on their own judgment or some documented formal standards? What happens to comments when a new doc version is released? What happens when entries become obsolete? What happens when comments are disputed? If the goal is (2) what kind of wiki contributions are being solicited ("I don't understand what this sentence means"? a complete rewrite of a section?) and how is that communicated? Who will take a long string of wiki comments constituting a discussion and condense them into something that can be submitted as a doc patch? (This I suspect is where the work is, where someone with good writing skills is needed.) Will this process be sufficient to raise the quality of the docs significantly, or are other steps also needed such as an attitude shift in what the core committers consider acceptable? If the goal is (1) above, it could potentially have a deleterious effect on the docs in that it will be easier to respond to requests to expand some description with, "there's no need since that is covered in (or belongs in) the wiki comments". All the above not withstanding, I too think a wiki is worth trying. But without doing a lot more than just "setting up a wiki", I sadly believe even a python.org supported wiki is doomed to failure. -- http://mail.python.org/mailman/listinfo/python-list