On 08/13/2009 08:46 AM, Paul Boddie wrote: > On 13 Aug, 16:05, ru...@yahoo.com wrote: >> 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. > > The ones on python.org seem to function reasonably well. I accept that > they could be more aggressively edited, but this isn't done because > there's a compromise between letting people contribute and keeping > things moderately coherent, with the former being favoured. For other > purposes, it would be quite acceptable to favour editorial control.
Yes, I agree. I should have mentioned this as an exception in my "wikis suck" diatribe. Although it far better than most wiki's I've seen, it is still pretty easy to find signs of typical wiki-ness. On the Documentation page my first click was on AnnotableDocumentation: 404. Second try, DoumentationDiscussion: two very short paragraphs dated 2003. After that I found some useful (in general though not what I was looking for) information but not a good first impression. (Well not exactly first, in fairness I have used other wiki sections such as the Templating page and found them very useful.) > I won't argue that providing infrastructure solves a problem - that's > precisely the kind of thing I was criticising when I noted that some > people will readily criticise the choice of tools to do a job instead > of focusing on the job that has to be done - and you need people who > are reasonably competent editors, but Wiki solutions remove a lot of > technical barriers. I'm not arguing for the flavour of Wiki which > implies unfettered, anonymous access from everyone on the Internet, > either: the kind of Wiki that detractors portray all Wiki solutions as > being in order to further their super-special "it has to fit like a > glove or it's totally unusable" software agenda. It's quite possible > to have people with somewhat more privileges than others in order to > keep the peace, and they don't all need to have an entrenched > editorial interest: on the current python.org Wiki sites, most of the > administrators don't have an active interest in most of the content, > but they are able to exercise control when it's clear that some > contributors aren't particularly interested in actually improving the > content. > > As well as having an active community effort around the existing > python.org Wiki sites, there are also people who are interested in > improving these offerings. What worries me is that despite such > activity and such interest, many people will continue to lament the > lack of vitality (or whatever other metric) of the general python.org > offering, whilst retaining a blind spot for the obvious contribution > that the Wikis can make to such improvement efforts. I encourage > people to use wiki.python.org a lot more, should they be looking to > improve the wealth of information provided by the community. Again, I agree with all of that. But my main interest is in improving the standard docs that are distributed with Python and I question a wiki's role in that. I took a look at the PHP docs last night which seem pretty well done. The User Comments looked rather as I expected, there was useful info but most did not contain documentation quality writing. So if they are used as a source for improving the docs, there clearly must be a pretty large amount of editorial effort required, although much of it is probably just filtering out comments that don't provide any information appropriate for inclusion in the docs. They list 38 names under "User Note Maintainers" (http://www.php.net/manual/en/preface.php) Unfortunately I couldn't find a description of what these people actually do. I don't know how much work was involved in removing the comments that are no longer there. Again, I don't mean to sound like I am dissing the idea of annotatable docs -- I think it is a good idea and will provide useful supplementary information. But I continue to question whether this will result in improvements in the docs themselves (which is my main interest) unless: 1. The purpose of the wiki is clearly "marketed" as soliciting suggestions, rewrites, etc destined ultimately for inclusion in the docs. 2. There is a dedicated core of doc-competent volunteers focused on extracting, condensing and editing the user comments and getting them into the docs, either directly (if the volunteers are committers -- unlikely) or through the existing tracker system. And this still fails to address the problems with the docs that aren't amenable to fixing via the tracker system. At least two of those problems are: 1. Difficultly in making large organizational changes. 2. Prevalent opinion among doc approvers that the current excessively terse style is desirerable. -- http://mail.python.org/mailman/listinfo/python-list
