On Sun, Mar 11, 2012 at 10:04, Maciek Sokolewicz <maciek.sokolew...@gmail.com> wrote: > > On 11 March 2012 02:40, Jesus M. Castagnetto <je...@castagnetto.com> wrote: >> >> Sorry to come so late in this discussion. But there are guidelines for >> more than a decade on how to handle notes: >> >> http://doc.php.net/php/dochowto/chapter-user-notes.php >> >> Just in case you did not see it: >> >> User Note Editing Guidelines [...] >> >> If you are in doubt about what to do with a note, you may ask for help on >> the php-notes mailing list (or phpdoc, if what you're doing involves the >> documentation proper). >> >> >> > Hi Jesus, > > I know those guidelines exist, I even linked to them from my original post. > However, those guidelines aren't very complete. They give a very rough > overview, which I agree with completely. There are tons of notes however, > which fall somewhere in between the categories supplied in the guidelines. > > What I'm mainly trying to say is that I personally think we don't need a > zillion examples of how to use a basic function to perform a specific task. > Most notes (these days) contain such code. Some are still quite general (ie. > people post an example of how preg_split can be used to limit a sentence to > a number of words), others are extremely specific (ie. I've seen posts where > people show a function to the amount of days between carnival and easter) or > possibly numerous with a little usefulnus, but mainly a lot of cluttering > (ie. people post date() monthnames in different languages, spanish, russian, > chinese, french, german, etc. There were at least 30 of these last time I > checked. Too many to add as an example, and so many that they obscure other > notes). > > My problem with all this is that it's usually not general enough to > integrate into the manual itself. Because when I view the manual, I want to > know how a function works, I don't care for an extremely specific use of the > function for a task that I don't even understand by itself. > The second problem I have with such things is that there are simply too many > notes for certain functions present in my opinion. When you have more than > 100 notes(!!) on a single page, finding the one thing you want is neigh > impossible. Ronald argued against this, while I think it is important to > moderate them more strictly and keep not only the manual itself, but also > the notes, more readable. > > I was hoping this last part would spark some more discussion, but > unfortunately, it has not.
Its a very difficult topic. On one hand, I completely agree with you - but on the other hand I know crapload of people that actually do copy&paste programming exclusively from the manual notes. Its is a sick thing to watch, but this is exactly why PHP is so cool. Anyone can create cool stuff, and the amount of random examples in the notes is crucial for the novice adoption. Everyone has to begin somewhere. -Hannes
