On Fri, Feb 24, 2012 at 1:54 PM, Maciek Sokolewicz
<maciek.sokolew...@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

Reply via email to