Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Dev

[Vote] Add commentary system to httpd docs

 

 

Apache dev RSS feed   Index | Next | Previous | View Threaded


rumble at cord

May 4, 2012, 6:58 AM

Post #1 of 12 (882 views)
Permalink
[Vote] Add commentary system to httpd docs

I'll be a bad boy and top-post on this reply, as well as add dev@ to the
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
http://wiki.apache.org/httpd/DocsCommentSystem

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
general population.

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.

With regards,
Daniel.

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?
>
> Shosholoza.
>
> --
> Rich Bowen
> rbowen [at] rcbowen <mailto:rbowen [at] rcbowen> :: @rbowen
> rbowen [at] apache <mailto:rbowen [at] apache>
>
>
>
>
>
>


rbowen at rcbowen

May 4, 2012, 7:48 AM

Post #2 of 12 (867 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On May 4, 2012, at 9:58 AM, Daniel Gruno wrote:

> [+/-1] Add commentary system to the trunk documentation.

Obviously, I'm +1 on this, as one of the folks who's been gently pushing for it for years. This is something that the PHP docs do right. Integrating comments into the documentation is a pretty big undertaking, but in the long run will make the docs more what our audience needs and is asking for.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


jblond at gmail

May 4, 2012, 8:17 AM

Post #3 of 12 (870 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

+1
> [+/-1] Add commentary system to the trunk documentation.


trawick at gmail

May 4, 2012, 9:34 AM

Post #4 of 12 (856 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

[+1] Add commentary system to the trunk documentation.


sf at sfritsch

May 4, 2012, 11:41 AM

Post #5 of 12 (858 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On Friday 04 May 2012, Daniel Gruno wrote:
> [+/-1] Add commentary system to the trunk documentation.

+1


i.galic at brainsware

May 4, 2012, 12:04 PM

Post #6 of 12 (862 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

> [+1] Add commentary system to the trunk documentation.


This may be worth a separate thread, but I'll just ask
it here, before I forget about it:

Any chance we'll see a backport of this to /current/ ?
If so, will we display the same comments as in /trunk/ ?

So long,

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


DRuggeri at primary

May 4, 2012, 2:24 PM

Post #7 of 12 (856 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On 5/4/2012 8:58 AM, Daniel Gruno wrote:
> [+/-1] Add commentary system to the trunk documentation.

+1

--
Daniel Ruggeri


covener at gmail

May 4, 2012, 5:18 PM

Post #8 of 12 (862 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

> [+/-1] Add commentary system to the trunk documentation.

+1


rbowen at rcbowen

May 4, 2012, 5:33 PM

Post #9 of 12 (861 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On 2012 5 4 15:04, "Igor Galić" <i.galic [at] brainsware> wrote:
>
>
> > [+1] Add commentary system to the trunk documentation.
>
>
> This may be worth a separate thread, but I'll just ask
> it here, before I forget about it:
>
> Any chance we'll see a backport of this to /current/ ?
> If so, will we display the same comments as in /trunk/ ?
>

I would assume that if the test is successful we would expand it to current
and 2.2. As to whether each branch has their own comments, I think they
probably should, but thats still to be decided.

--
Rich Bowen
rbowen [at] rcbowen


chrisd at pearsoncmg

May 4, 2012, 6:43 PM

Post #10 of 12 (861 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

Daniel Gruno wrote:

> [+/-1] Add commentary system to the trunk documentation.

+1

Chris.

--
GPG Key ID: 088335A9
GPG Key Fingerprint: 86CD 3297 7493 75BC F820 6715 F54F E648 0883 35A9


rainer.jung at kippdata

May 5, 2012, 11:54 AM

Post #11 of 12 (852 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On 04.05.2012 15:58, Daniel Gruno wrote:

[+1] Add commentary system to the trunk documentation.

Thanks for pushing this and helping Rich and the project with so much
positive energy.

Rainer


rumble at cord

May 6, 2012, 3:31 AM

Post #12 of 12 (847 views)
Permalink
Re: [Vote] Add commentary system to httpd docs [In reply to]

On 04-05-2012 21:04, Igor Galić wrote:
>
>> [+1] Add commentary system to the trunk documentation.
>
>
> This may be worth a separate thread, but I'll just ask
> it here, before I forget about it:
>
> Any chance we'll see a backport of this to /current/ ?
> If so, will we display the same comments as in /trunk/ ?
>
> So long,
>
> i
>

I think the latter question, and others similar to it, needs to be
answered before we answer the first one.

I've compiled a preliminary list of questions that we should discuss
before we start discussing bigger questions like backporting (we've only
just begun discussing using it in trunk after all :) ). The questions
I've gathered so far can be found at
http://wiki.apache.org/httpd/DocsCommentSystem#Questions_for_further_discussion
, and when this vote hopefully passes and we start rolling out comment
sections to more pages in trunk, I'd appreciate if people would start
getting the ball rolling on these questions. They're not life-or-death,
as we can always change the options for our comments, but it would be
nice to have this all sorted out before we start discussing issues like
backporting it.

So, give it a read and do let me/us know here on the list what you think
about possible solutions to the questions outlined in the Wiki.

With regards,
Daniel.

Apache dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.