I've been maintaining notes in the manual off and on since I came to the
PHP project, quite a few years ago.
A few days ago I deleted a note, and the author sent a mail to the
php-general list complaining about it. The answer by Dan was basically
that the notes maintainers are overzealous and the author should contact
the person who had deleted the note for clarification. Though I
personally think saying that notes maintainers are overzealous is simply
incorrect and may even be interpreted as insulting (yes, I do feel that
way), that's not the point I'm trying to discuss.
The point I'm trying to bring up is: what notes do we want to keep in
the manual, and what notes do we not want in there.
http://doc.php.net/php/dochowto/chapter-user-notes.php
This url gives a few guidelines, but mainly focuses on the difference
between deleting and rejecting notes.
Personally, I hold to the following guidelines (set by myself, since
none really exist):
- does the note add any valuable insight into the mechanism of the
function / behaviour described ?
- does the note clarify the use of the function / behaviour described?
- does the note explain something which is clearly missing from the
documentation?
And in the case of an example function:
- is the code provided easy to interpret? (ie. are there comments
explaining any 'difficult' behaviour) and
- is the code provided useful to many people?
Obviously, since these are my own guidelines, I was wondering what the
rest thinks about this. The reason I'm using such "strict" guidelines is
simply to make the manual notes readable. If you look at a page such as
http://www.php.net/manual/en/function.strtotime.php, there are > 100
notes present. Trying to find something useful to you is simply
impossible on such a page. Trying to clean that page to only leave
samples that solve very common problems or clarify the behaviour of the
function is IMO a good thing. That does often mean removing various code
samples of the type "this might be useful to some people".
I am wondering what others think, should we try to thin down the stream
of notes and simply delete notes that have little to say about the
actual function or are of relatively little use to the common PHP coder?
Or should we leave as many notes as possible with examples so people can
find *anything* in there? Possibly leading to unwieldy long lists of notes?
What do YOU think? Feel free to comment / criticise / be constructive ;)
- Tul
P.S. Sent to both php-doc and php-notes since very few people actively
read the notes list.
