-----Original Message----- From: Hannes Magnusson [mailto:hannes.magnus...@gmail.com] Sent: Thursday, April 08, 2010 6:01 AM To: Bill Salak Cc: Rasmus Lerdorf; PHP Documentation List Subject: Re: [PHP-DOC] User commentary in docs
On Wed, Apr 7, 2010 at 06:41, Bill Salak <b...@devtemple.com> wrote: >>Yes, documentation is tricky. People, especially PHP users, come from >>so > many different experience backgrounds that it is almost impossible to > write one set of docs that speaks to everyone. There are things in > the user comments that I have seen people pick up on that I would have > thought was completely obvious and unnecessary to document, but turn > out to be extremely helpful to a few. I think the bulk of our user > comments are never going to get folded back into the main docs as they > tend to repeat the main docs in a slightly different way, but are > valuable in their own right simply because they explain the same thing from a different perspective. > > I have personally drawn insight from the user comments area many times > over the years for exactly these reasons you point out - it's a > different voice or perspective and sometimes that is what is needed > rather than only new information. The volume and type of messages > found in the user comments is saying something. I think what you're > seeing are the users looking for an official php forum to build community around. > > I think there is a place somewhere in association with the official > php documentation for large collections of user submitted examples and voices. >I don't think we want to maintain such forum. We don't even have the manpower to maintain the current user notes, so expanding upon that will require more people to help out - which we simply do not have. There are also literally thousands of support/codesnippet/.. forums around the web, in various languages and forms. It shouldn't be hard to find such forum if the user wants to find it. The user notes are awesome. I used them extensively when I first started learning PHP, and still today I read notes people have submitted on "underdocumented things". -Hannes Hannes, I definitely understand the resource issues and agree with your points. My statements were probably a bit open-ended and idealistic however if it's agreed that the point is valid - a pragmatic approach might look something like an extension of the administrative capabilities of user notes to not only allow for removal but also archiving. A link to archived notes could be provided somewhere on the doc page. This would allow for the retention of notes which are deemed valuable enough to keep while still being able to prune obvious noise or incorrect submissions. I also suggest requiring users to select the php major/minor version they are supplying a note for with the default being the current version of php the doc page is referring to. This information would be helpful now but even more so if you are to keep a note archive. A further expansion of this idea would be to create a facility to prune all notes by php version when official support for a version is dropped. If these suggestions are determined to be desirable improvements I'll spend my time to implement these enhancements if someone more experienced with the system is willing to point me in the right direction. If someone has better ideas I'm willing to help on those as well. If I'm alone on thinking this would be a valuable addition then I digress. ----- Bill
