rumble at cord
May 4, 2012, 6:58 AM
Post #1 of 12
I'll be a bad boy and top-post on this reply, as well as add dev@ to the
[Vote] Add commentary system to httpd docs
list of recipients.
In docs@, we have been discussing the possibility of adding comments to
the various pages in our documentation. As the discussion has
progressed, we have settled on the idea of trying out Disqus as a
commentary system for the documentation, and I have authored a proposal
on the practical implementation of this.
As this is a rather large change to the documentation (if passed), Eric
Covener advised me to notify both mailing lists as well as give a bit
more information on how exactly this will work and why we felt it was a
good idea to try out a commenting system. That information is located at
We have, to give it a test spin, rolled out these proposed changed to
the rewrite section of the trunk documentation,
http://httpd.apache.org/docs/trunk/rewrite/ (do note that the
mod_rewrite reference document is NOT a part of this test), and we'd
very much like you to review these changes and let us know what you
think of this solution. If everybody is happy about it, we can try to
roll it out on a bit more pages, and see how it is received by the
So, I am calling a vote on whether or not to proceed with rolling out
this test to a portion of our trunk documentation for further testing.
[+/-1] Add commentary system to the trunk documentation.
On 03-05-2012 15:54, Rich Bowen wrote:
> 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.
> I digress.
> 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?
> Rich Bowen
> rbowen [at] rcbowen <mailto:rbowen [at] rcbowen> :: @rbowen
> rbowen [at] apache <mailto:rbowen [at] apache>