atom feed17 messages in net.php.lists.phpdoc[PHP-DOC] user comments of the future
FromSent OnAttachments
Philip OlsonMar 27, 2009 9:50 pm 
Cindy Sue CauseyMar 27, 2009 10:54 pm 
Daniel ConvissorMar 28, 2009 7:41 am 
Kalle Sommer NielsenMar 28, 2009 8:44 am 
Philip OlsonMar 28, 2009 9:25 am 
Philip OlsonMar 28, 2009 9:28 am 
Nathan AdamsMar 28, 2009 9:35 am 
Daniel ConvissorMar 28, 2009 9:39 am 
Philip OlsonMar 28, 2009 9:40 am 
Philip OlsonMar 31, 2009 1:05 pm 
Richard QuadlingApr 1, 2009 1:06 am 
Nathan AdamsApr 1, 2009 8:59 pm 
G. T. Stresen-ReuterApr 2, 2009 4:06 am 
JulietteApr 2, 2009 4:46 am 
Hannes MagnussonApr 2, 2009 6:20 am 
Philip OlsonApr 3, 2009 11:22 am 
Daniel ConvissorApr 13, 2009 5:52 am 
Subject:[PHP-DOC] user comments of the future
From:Philip Olson (
Date:Mar 27, 2009 9:50:17 pm

Hello fellow documentation geeks,

We've discussed our comment system a few times but let's finally do something about it. Let's first discuss what our ideal user interactive system would be, then design a system while keeping in mind our resource limitations.

So, if we want a system designed to easily allow users contributions to the documentation itself then we'll have a system more like the one used by the django book:


Where comments apply to paragraphs/sections thus keeping context. In this scenario it would be easy to do things like suggest a grammar fix to a specific line, or comment on a specific example or tidbit. Also, they could directly link to our [upcoming] online editor for simple editing and committing into the patch queue. The possibilities are near endless. And eventually some of these people will want to contribute directly so it may in fact be a ploy to lure contributors to the PHP project.

Now if we want a system that's meant to house code snippets, tidbits, gotchas, tips, and whatever else people think of then we'd put more emphasis on note tagging, categorization and voting. And one tag can be 'question' where once chosen the user is gracefully told how and where to ask questions. Something like that.

And, it's possible to have both.

Concerns: We'd be asking our mirrors to do more work, and it's something else to develop and maintain. I don't know if we really want to promote the idea that we're a code repository but then again it seems to be what users want but I don't know... and maybe voting would take care of the QA.

So, think about this while envisioning the PHP Manual of tomorrow and let's get 'er done!

Regards, Philip

P.S. About 150,000 user notes have been submitted over the past 10 years, and roughly 15% remain.