Re: About note maintenance; when to delete notes.

On Fri, Feb 24, 2012 at 1:54 PM, Maciek Sokolewicz <maciek.sokolewicz@gmail.com> wrote: > 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. I disagree. The problem is not that there are too many notes. (That's a bit like complaining the internet has too many pages). The problem on that page is that strtotime isn't documented in such a way as to make the many notes unnecessary. > 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 ;) Notes, to me, are an indication of what is lacking in the manual. If you want to delete a note, make sure the content/idea/concept has already been put into the documentation somehow. Update the documentation, *then* delete the note. Simply deleting a note adds no value to the project. A page with many notes is a page in need of a re-write, not a note purge. -Ronabop