On 18 Aug, 05:19, ru...@yahoo.com wrote: > > 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.
Well, "Annotatable Documentation" is an external link. All we can do in such cases is to tidy such stuff up, mark it as invalid, or remove it. > Second try, DoumentationDiscussion: two very short paragraphs dated 2003. Right. There are parts of the Wiki which were used actively in the past but which have fallen into disrepair. Some pages lack focus - they've been created according to "old school" Wiki conventions which I regard as being somewhat obsolete (just creating new pages all over the place to cover whatever happens to be in the writer's head at the time) - and every now and again, I attempt to rationalise these pages and focus their content. > 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.) It needs work, of course. [...] > 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. Indeed. There's always the editorial bottleneck unless it's a total free-for-all situation. I've remarked before about how user comments don't necessarily add significantly to documentation, which is an assertion that some people make, and there definitely does need to be a process of integrating the best feedback into the main work. The crucial difference between a Wiki and an annotation system is the combination of the contribution and editorial aspects in a Wiki - you edit the actual work, and people can decide whether it's a good edit or not - in contrast to their separation in most annotation systems. In some cases, strict annotation systems are probably better: the GPLv3 annotation system was oriented towards discussion of the text, and that's not so effectively done in a Wiki. > 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. Where there's a separation of annotation and editing, I worry about the editorial bottleneck. I also worry about "handprint" edits more generally, where people just want to leave their touch on the work without actually contributing anything of substance. > 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. I'm happy to see tangential work rather than stuff which fills exactly the same role as the current documentation. For example, the Python module of the week articles (PyMOTW, [1]) are exactly the kind of tangential work that could be encouraged, even though that is not so much a collaborative work itself. Paul [1] http://www.doughellmann.com/PyMOTW/ -- http://mail.python.org/mailman/listinfo/python-list
