RE: [PHP-DOC] User commentary in docs
-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 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
Re: [PHP-DOC] User commentary in docs
On Wed, Apr 7, 2010 at 06:41, Bill Salak 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
RE: [PHP-DOC] User commentary in docs
>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. Probably not inline with the content as it IS allot of noise and not necessarily documentation. Possibly this is a link from the docs page to this thing I am postulating. If that can be accommodated at some point - I think there would be value to it.
Re: [PHP-DOC] User commentary in docs
Hello everyone. The user notes is a great resource to most new users. However there are snippets of junk there that are not only useless, but they even get confusing at some time. I think there would be great to start a program of checking such comments, I can help if needed (not yet involved in this in any way). Another opinion would be all the notes removed from the doc page and add into a "read user feedback" sub-page so whoever needs it can access it, or simply allow comments for certain kind of pages. -- Stelian On Tue, Apr 6, 2010 at 8:01 PM, Rich Bowen wrote: > > On Apr 6, 2010, at 12:56 PM, Philip Olson wrote: > > if you want to support user commentary, the only sane way is to >>> regularly peruse those comments, trash the garbage, and incorporate >>> the reasonable comments into the documentation proper. just leaving >>> the comments there in perpetuity is, IMHO, a terrible idea. >>> >> >> That's was the original idea, and once worked well. However, over time we >> started leaving information that looked remotely useful so it's grown [out >> of control]. And besides, it's difficult to know what a proper user note is >> as I reckon we all have different definitions. And over time users have come >> to expect the user notes as is, which are remotely related tips and code >> snippets. I think simply removing them all would cause the PHP world to >> crash upside down. :) All thoughts and ideas welcome. >> > > I think that in an ideal world, the comments all get integrated, and then > deleted. This is impractical, given the sheer scope of the problem, but it's > an ideal to strive towards, and an excellent place to point folks who want > to get involved in the documentation process. > > --Rich > >
Re: [PHP-DOC] User commentary in docs
On Apr 6, 2010, at 12:56 PM, Philip Olson wrote: if you want to support user commentary, the only sane way is to regularly peruse those comments, trash the garbage, and incorporate the reasonable comments into the documentation proper. just leaving the comments there in perpetuity is, IMHO, a terrible idea. That's was the original idea, and once worked well. However, over time we started leaving information that looked remotely useful so it's grown [out of control]. And besides, it's difficult to know what a proper user note is as I reckon we all have different definitions. And over time users have come to expect the user notes as is, which are remotely related tips and code snippets. I think simply removing them all would cause the PHP world to crash upside down. :) All thoughts and ideas welcome. I think that in an ideal world, the comments all get integrated, and then deleted. This is impractical, given the sheer scope of the problem, but it's an ideal to strive towards, and an excellent place to point folks who want to get involved in the documentation process. --Rich
Re: [PHP-DOC] User commentary in docs
On 04/06/2010 09:52 AM, Rich Bowen wrote: > > On Apr 6, 2010, at 12:05 PM, Rasmus Lerdorf wrote: > >> It's custom code for our docs, but it probably wouldn't be too hard to >> bolt onto another system. Start here: > > Thanks so much for the thorough summary. This is very helpful. > > As to whether we'll actually do this, I don't know. Expect a certain > amount of resistance. User commentary without a concerted effort to > incorporate that commentary back into the docs is, as Robert says, a > recipe for unlimited quantities of crap attached to the docs. On the > other hand, the Apache HTTPD docs are *WAY* smaller than the PHP docs. > We have (last time I counted) a total of 229 doc files. I count 10809 > .xml files in the doc-en svn repo. So incorporating that feedback is a > much smaller job than it is with the PHP docs. > > Mostly I'm feeling that our docs don't answer the questions that folks > are actually asking, and I am looking around for ways to rectify that. > This is one idea that was floated. 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. -Rasmus
Re: [PHP-DOC] User commentary in docs
On Apr 6, 2010, at 9:41 AM, Robert P. J. Day wrote: > On Tue, 6 Apr 2010, Rich Bowen wrote: > >> A few of us on the Apache HTTP Server documentation team are >> investigating what it would take to add a user commentary system to >> the Apache HTTPD docs, like that used on the PHP docs. What software >> is used for that? Is it easily reusable in other places? Where can I >> get some more info about it? > > please reconsider that idea. as it is, there's simply too much > nonsense that's been added by users at the PHP docs site. here's an > example: > > http://www.php.net/manual/en/language.variables.php > > if you look closely at that page, it's simply a ***table of > contents***, fer cryin' out loud. nevertheless, numerous commenters > found it necessary to expound on it. for what conceivable purpose? At one point in time that wasn't a TOC, as instead it contained all those sub-sections on one page. The notes remained there, however. There are tools to move around notes (even entire pages of notes), and scripts to find orphaned notes, but honestly user notes has become a low priority to most everyone. Sad, but true. > > if you want to support user commentary, the only sane way is to > regularly peruse those comments, trash the garbage, and incorporate > the reasonable comments into the documentation proper. just leaving > the comments there in perpetuity is, IMHO, a terrible idea. That's was the original idea, and once worked well. However, over time we started leaving information that looked remotely useful so it's grown [out of control]. And besides, it's difficult to know what a proper user note is as I reckon we all have different definitions. And over time users have come to expect the user notes as is, which are remotely related tips and code snippets. I think simply removing them all would cause the PHP world to crash upside down. :) All thoughts and ideas welcome. Regards, Philip
Re: [PHP-DOC] User commentary in docs
On Apr 6, 2010, at 12:41 PM, Robert P. J. Day wrote: http://www.php.net/manual/en/language.variables.php if you look closely at that page, it's simply a ***table of contents***, fer cryin' out loud. nevertheless, numerous commenters found it necessary to expound on it. for what conceivable purpose? if you want to support user commentary, the only sane way is to regularly peruse those comments, trash the garbage, and incorporate the reasonable comments into the documentation proper. just leaving the comments there in perpetuity is, IMHO, a terrible idea. So, what you do is log in, and then go to that page and delete the irrelevant comments (in this particular case, all of them) and incorporate the relevant ones (in this case, none of them) into the content of the page. It's a really great way for someone to get involved in the documentation process. --Rich
Re: [PHP-DOC] User commentary in docs
On Tue, 6 Apr 2010, Rasmus Lerdorf wrote: > Robert, you could pitch in and help clean up and incorporate the > comments then. I am sure Dan and the others would appreciate the > help. > There is simply too much user feedback and too few volunteers to get > them all into the documentation in a timely manner. We found long > ago that the best alternative was to have a quick way to get rid of > bad comments and let the majority of stuff through because there > really is some good contents in there. > You may not like them, but I can tell you that the huge majority of > feedback we get on them is positive. Almost everywhere I go, no > matter where it is in the world, the user comments in the > documentation is something people say they love about PHP. sorry, that last post of mine came across as unnecessarily harsh, and i apologize. sure, after i dig out from under my current project, i can probably help out. and, yes, there are the occasional gems of advice, no doubt about it. but you do appreciate my original observation regarding pages like this: http://www.php.net/manual/en/language.variables.php the fact that readers *can* comment should not suggest that they *must* comment. and, more importantly, they should try to comment on the appropriate page so that their comment makes sense. rday -- Robert P. J. Day Waterloo, Ontario, CANADA Linux Consulting, Training and Kernel Pedantry. Web page: http://crashcourse.ca Twitter: http://twitter.com/rpjday
Re: [PHP-DOC] User commentary in docs
On Apr 6, 2010, at 12:05 PM, Rasmus Lerdorf wrote: It's custom code for our docs, but it probably wouldn't be too hard to bolt onto another system. Start here: Thanks so much for the thorough summary. This is very helpful. As to whether we'll actually do this, I don't know. Expect a certain amount of resistance. User commentary without a concerted effort to incorporate that commentary back into the docs is, as Robert says, a recipe for unlimited quantities of crap attached to the docs. On the other hand, the Apache HTTPD docs are *WAY* smaller than the PHP docs. We have (last time I counted) a total of 229 doc files. I count 10809 .xml files in the doc-en svn repo. So incorporating that feedback is a much smaller job than it is with the PHP docs. Mostly I'm feeling that our docs don't answer the questions that folks are actually asking, and I am looking around for ways to rectify that. This is one idea that was floated.
Re: [PHP-DOC] User commentary in docs
On 04/06/2010 09:41 AM, Robert P. J. Day wrote: > On Tue, 6 Apr 2010, Rich Bowen wrote: > >> A few of us on the Apache HTTP Server documentation team are >> investigating what it would take to add a user commentary system to >> the Apache HTTPD docs, like that used on the PHP docs. What software >> is used for that? Is it easily reusable in other places? Where can I >> get some more info about it? > > please reconsider that idea. as it is, there's simply too much > nonsense that's been added by users at the PHP docs site. here's an > example: > > http://www.php.net/manual/en/language.variables.php > > if you look closely at that page, it's simply a ***table of > contents***, fer cryin' out loud. nevertheless, numerous commenters > found it necessary to expound on it. for what conceivable purpose? > > if you want to support user commentary, the only sane way is to > regularly peruse those comments, trash the garbage, and incorporate > the reasonable comments into the documentation proper. just leaving > the comments there in perpetuity is, IMHO, a terrible idea. Robert, you could pitch in and help clean up and incorporate the comments then. I am sure Dan and the others would appreciate the help. There is simply too much user feedback and too few volunteers to get them all into the documentation in a timely manner. We found long ago that the best alternative was to have a quick way to get rid of bad comments and let the majority of stuff through because there really is some good contents in there. You may not like them, but I can tell you that the huge majority of feedback we get on them is positive. Almost everywhere I go, no matter where it is in the world, the user comments in the documentation is something people say they love about PHP. -Rasmus
Re: [PHP-DOC] User commentary in docs
On Tue, Apr 6, 2010 at 12:41, Robert P. J. Day wrote: > > if you want to support user commentary, the only sane way is to > regularly peruse those comments, trash the garbage, and incorporate > the reasonable comments into the documentation proper. just leaving > the comments there in perpetuity is, IMHO, a terrible idea. Hence my "Pandora's Box" statement. FYI: http://doc.php.net/php/notes_stats.php -- daniel.br...@parasane.net || danbr...@php.net http://www.parasane.net/ || http://www.pilotpig.net/ Looking for hosting or dedicated servers? Ask me how we can fit your budget!
Re: [PHP-DOC] User commentary in docs
On Tue, 6 Apr 2010, Rich Bowen wrote: > A few of us on the Apache HTTP Server documentation team are > investigating what it would take to add a user commentary system to > the Apache HTTPD docs, like that used on the PHP docs. What software > is used for that? Is it easily reusable in other places? Where can I > get some more info about it? please reconsider that idea. as it is, there's simply too much nonsense that's been added by users at the PHP docs site. here's an example: http://www.php.net/manual/en/language.variables.php if you look closely at that page, it's simply a ***table of contents***, fer cryin' out loud. nevertheless, numerous commenters found it necessary to expound on it. for what conceivable purpose? if you want to support user commentary, the only sane way is to regularly peruse those comments, trash the garbage, and incorporate the reasonable comments into the documentation proper. just leaving the comments there in perpetuity is, IMHO, a terrible idea. rday -- Robert P. J. Day Waterloo, Ontario, CANADA Linux Consulting, Training and Kernel Pedantry. Web page: http://crashcourse.ca Twitter: http://twitter.com/rpjday
Re: [PHP-DOC] User commentary in docs
On 04/06/2010 08:25 AM, Philip Olson wrote: > > On Apr 6, 2010, at 7:56 AM, Rich Bowen wrote: > >> A few of us on the Apache HTTP Server documentation team are investigating >> what it would take to add a user commentary system to the Apache HTTPD docs, >> like that used on the PHP docs. What software is used for that? Is it easily >> reusable in other places? Where can I get some more info about it? > > The system is custom and was written in the 90's. You say that like it is a bad thing. It's like a well-aged red wine. -Rasmus
Re: [PHP-DOC] User commentary in docs
On 04/06/2010 07:56 AM, Rich Bowen wrote: > A few of us on the Apache HTTP Server documentation team are > investigating what it would take to add a user commentary system to the > Apache HTTPD docs, like that used on the PHP docs. What software is used > for that? Is it easily reusable in other places? Where can I get some > more info about it? It's custom code for our docs, but it probably wouldn't be too hard to bolt onto another system. Start here: http://svn.php.net/viewvc/web/php/trunk/manual/add-note.php?view=markup That's the end point users use to add a note to the manual. The note gets sent to a central server (master.php.net). The receiving script for those notes is: http://svn.php.net/viewvc/web/php-master/trunk/entry/user-note.php?view=markup And the schema for the central notes DB is here: http://svn.php.net/viewvc/web/php-master/trunk/note.sql?view=markup There is a note management console at: http://master.php.net/manage/user-notes.php The source for that console is here: http://svn.php.net/viewvc/web/php-master/trunk/manage/user-notes.php?view=markup Then, to get the notes back out onto the mirror sites we have an rsync server which runs a cronjob: http://svn.php.net/viewvc/systems/trunk/update-phpweb-backend?view=markup That cron job calls this script: http://svn.php.net/viewvc/web/php-master/trunk/scripts/update-user-notes?view=markup which fetches the user notes from master with this script: http://svn.php.net/viewvc/web/php-master/trunk/fetch/user-notes.php?view=markup So, now we have all the user notes on the rsync server. All the mirror sites fetch those notes every couple of hours. So all that is left to do is to show the notes. The code to show them is here: http://svn.php.net/viewvc/web/php/trunk/include/shared-manual.inc?view=markup See the various manual_note* functions in that file. Also note that people who are "logged in" by having the MAGIC_COOKIE set can click directly on a note to reject it or edit it on the master server from the manual page instead of having to go hunting for it manually in the note console. There are also a couple of helper scripts here: http://svn.php.net/viewvc/web/doc/trunk/scripts/ I probably missed a few bits, but that should be the bulk of it. It might be easier to just steal bits and pieces of this and write your own from that. -Rasmus
Re: [PHP-DOC] User commentary in docs
On Apr 6, 2010, at 7:56 AM, Rich Bowen wrote: > A few of us on the Apache HTTP Server documentation team are investigating > what it would take to add a user commentary system to the Apache HTTPD docs, > like that used on the PHP docs. What software is used for that? Is it easily > reusable in other places? Where can I get some more info about it? The system is custom and was written in the 90's. It contains several files spread throughout the php.net SVN system, but my old brain is unable to offer many specifics. The following idea revolves around updating them: - http://wiki.php.net/ideas/usercomments But let's first identify the current system. Hannes researched this a bit while helping a fellow implement a user comment rating system, so he'll probably have greater insight. The PEAR manual also implemented a version (in the last few years) so it might be easier to implement. I'll start updating that wiki idea. And who knows, maybe the two documentation projects can come up with code that'll help each other out. Regards, Philip
Re: [PHP-DOC] User commentary in docs
On Tue, Apr 6, 2010 at 10:56, Rich Bowen wrote: > A few of us on the Apache HTTP Server documentation team are investigating > what it would take to add a user commentary system to the Apache HTTPD docs, > like that used on the PHP docs. What software is used for that? Is it easily > reusable in other places? Where can I get some more info about it? Simplest way to check it out is to view the source code. Heads up, though, Rich: you're opening Pandora's Box. With it comes required moderation and the occasional angry email from someone who is outraged that you would reject their version of a regexp that's been presented in a trillion other ways already. ;-P -- daniel.br...@parasane.net || danbr...@php.net http://www.parasane.net/ || http://www.pilotpig.net/ Looking for hosting or dedicated servers? Ask me how we can fit your budget!
