Erik Berglund wrote: > I.m an Assistant Professor in computer science at Linkoping > University, Sweden and I am studying the PHP manual with regards to the > user comments section. If you feel you have time and knowledge please take > the time to answer a few questions:
Dear Erik Berglund! I am answering just for myself, not for the whole team. Other members of the team can have different opinion. > How important to the manual would you say the annotations by users are? For a manual readers, notes can be useful if they want to use a function which is not documented enough. Notes can be useful also for beginners as there are lots of examples. However, there are sometimes some myths and untruths. For expert readers, it's often faster to get the information missing in the manual other way - e.g. by reading sources. For manual writers, notes can contain useful tips for finding undocumented features. But there's also lots of clutter in the notes so it's hard work to reading all notes, deleting the wrong ones and incorporating the correct ones. Personally, I much more like our Bug system ( http://bugs.php.net/search.php?cmd=display&status=Open&bug_type%5B%5D=Documentation+problem ) - it's not so easy to report a bug so there is much better signal to noise ratio. > Have you in the past or are planning to rewrite the manual to include in > user annotations in the text, changing the manual due to user > contribution? Is this common, regular, seldom? It's constant, never ending work. Most of notes are rejected, some of them are incorporated. You can take a picture of notes volume at http://news.php.net/php.notes . > To what degree does the annotations in the manual link to or replace > discussion forums? We strongly discourage notes contributors to post questions and other topics belonging to discussion forums and we delete such notes. > What other manuals do you know of that use the same type of annotation > mechanism? E.g. MySQL manual uses similar mechanism. > What is your feeling regarding using a wiki instead, like the emacswiki, > where users can change the text directly? No way! In the notes, there are lots of clutter, inaccurate or misleading information and texts which in short shouldn't be contained in the manual. Everyone can contribute to the manual. But again - it's not so easy as Wiki and I am glad of it. > Where the addition of comments even across many parts of the manual or > focused on certain parts? What do you think this signifies (for either > case)? Most of comments are added to the commonly used functions. Some of them are of kind "this function can be used even for this". You can take a picture from the Notes Status (outdated a bit): http://marc.theaimsgroup.com/?l=phpdoc&m=109155130212306&w=2 Jakub Vrana
