rbowen at rcbowen
May 3, 2012, 6:54 AM
I've long been a fan of the PHP documentation - specifically, the way that they solicit commentary from readers, and then fold that commentary into the docs. Not only did it encourage me to comment on the docs, it also got me involved in the PHP documentation project, at least marginally. The barrier to entry is so low that all you have to do is be a writer.
As I've said elsewhere, our process seems to require that you be a programmer. I'd like to see what we can do to change that. This is why the docs@ list was split from the dev@ list in the first place. And it was at least in part why we started doing stuff in a wiki, although that hasn't been nearly as successful as I wished.
I'd like to brainstorm about how we can do something like the PHP docs - provide a way for end-users to comment on a given doc, and then have a process for moderating and folding those comments into the docs themselves.
The PHP docs team have offered us, on several occasions, their entire documentation infrastructure. I haven't even bothered to mention that to this list, because it would be an *enormous* change. I've discussed it in person with several docs folks, and the response has consistently been, yeah, that would be cool, but it's too big a change. But I'd be glad to have Phil write up something if people are at all interested.
Does anyone know of a way to integrate a third-party comment service like, say, disqus or whatnot, into our docs, so that we could get direct feedback from our audience? Or can you think of another way that we might do this?
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache