Re: [Result] Re: [Vote] Add commentary system to httpd docs
On 20.05.2012 14:47, Daniel Gruno wrote: This will effectively make for two (or three) new votes for adopting each piece: - Adopt a privacy policy for the docs and refer to the various tracking methods used as they get implemented - see the draft at http://wiki.apache.org/httpd/PrivacyPolicy Thanks for preparing this draft. As previously stated, I consider such a policy a mandatory requirement before integrating any tool into httpd.apache.org which systematically processes user data [1]. The section Additional tracking by third parties of the draft currently says: The Apache HTTP Server project makes use of additional third party tools, such as the Disqus commentary system, which itself may apply visitor tracking for internal purposes. In the interest of an early declaration, let me say that I'm (rather strongly) opposed to running the project's site in a way that requires us to have such a generic disclaimer in the privacy policy, for several reasons. First, my expectation would be that an ASF project, and in particular ours, is able to run the infrastructure of those features it considers essential for its operations on its own. It's true that some other projects are using Google Analytics, but this doesn't mean that others should follow this practice, IMO. Second, I see several technical issues when integrating third-party tools which basically rely on JS code being injected into the HTML on httpd.apache.org: surreptitious tracking is one of them, but it's also problematic from a security point of view: by pulling in JS from remote URLs we expose our visitors to the risk of running untrusted code in the context of our site. (As an aside: having to turn off JS for httpd.apache.org as a whole, as - rightfully - suggested in the draft privacy policy for effectively turning off GA, would have the collateral damage of disabling the newly-added syntax highlighting as well, which seems quite unfortunate.) Third, *iff* we really decide to do user tracking on httpd.apache.org, it should at least be opt-in, not opt-out, in my view (i.e., we should e.g. make sure to honor DNT: 1 headers before pulling in JS tracking code, and ensure that visitors agree to being tracked before we do so). - Implement the Disqus commentary system for the docs - see the proposal at http://wiki.apache.org/httpd/DocsCommentSystem In the meantime I skimmed over its Terms Of Service [2], and it took me only a short time to identify several elements which made me quite worried: a) User Content: Disqus is granted a a royalty-free, sublicensable, transferable, perpetual, irrevocable, non-exclusive, worldwide license to use, reproduce, modify, publish, list information regarding, edit, translate, distribute, syndicate, publicly perform, publicly display, and make derivative works of all such User Content etc. b) Changes to the service: We may, without prior notice, change the Service; stop providing the Service or features of the Service, to you or to users generally; or create usage limits for the Service. c) Advertisements: You agree that Disqus may include advertisements and/or content provided by Disqus and/or a third party (collectively Ads) as part of the implementation of the Service. This just a small sample of rules I consider highly problematic, and to be honest, they pretty much rule out the option of using Disqus on httpd.apache.org, I think. PHP's system, on the other hand, uses an approach [3] I'm completely comfortable with: no dependencies on third-party sites, comments are covered by a Creative Commons license, and do not rely on any remote JS code or so. - Implement visitor tracking for the docs so we can improve on them - see proposal at http://wiki.apache.org/httpd/DocsAnalyticsProposal I would highly prefer Piwik over the others (or more generally: a tool we run ourselves, not a third-party service). Kaspar [1] see also http://mail-archives.apache.org/mod_mbox/www-legal-discuss/200809.mbox/%3c48cf1c4a.1000...@rowe-clan.net%3E and other messages in that thread, e.g. [2] http://docs.disqus.com/help/29/ [3] http://www.php.net/manual/add-note.php
Re: [Result] Re: [Vote] Add commentary system to httpd docs
Sending to docs@ as well, as this applies to that list too. Grumpiness may occur, so apologies in advance. On 05/19/2012 09:32 AM, Kaspar Brand wrote: Looking at the call for votes [retained below for reference] and at the votes, I'm not sure if the +1 voters were aware of the specific mechanics of the Disqus comment system which is now embedded into all HTML below http://httpd.apache.org/docs/trunk/ [1], however. The vote did refer to a proposal on the apache wiki that specifically mentioned Disqus as the method of choice. If people were unaware of how Disqus operates then, frankly and with respect, they should aim to work with due diligence or ask questions before voting. It should be a well known fact that using third party tools will eventually result in visitor tracking occurring one way or another. If people would rather see us use a comment system developed and housed by Apache, then I'm sure we can figure something out, but it requires that people say so. Effectively, using Disqus means that even visiting an innocent page like http://httpd.apache.org/docs/trunk/license.html will already result in all sorts of drive-by tracking requests [2], among them Google Analytics (pulled in via httpd.disqus.com/thread.js). Based on the fact that there's currently no privacy policy for httpd.apache.org - which would make visitors aware of being tracked (and link to both the Disqus privacy policy [3] and the GA privacy policy [4]) - I believe that the vote should be repeated, with being recast to: [+/-1] Add the Disqus commentary system to the trunk documentation. Meh, it makes me a sad panda that we have to discuss this once again, but you may have a point here. I suppose it would be in the Apache spirit to keep our intentions as open as possible, which merits a privacy policy. I have already written up a draft for such a policy, and included the GA and Disqus techs used in the proposed comment system and analytics for the docs. It can be found at http://wiki.apache.org/httpd/PrivacyPolicy . It is loosely based on the policies that are in place for other Apache projects such as Lucene and Directory (which also makes use of GA on their sites). This will effectively make for two (or three) new votes for adopting each piece: - Adopt a privacy policy for the docs and refer to the various tracking methods used as they get implemented - see the draft at http://wiki.apache.org/httpd/PrivacyPolicy - Implement the Disqus commentary system for the docs - see the proposal at http://wiki.apache.org/httpd/DocsCommentSystem - Implement visitor tracking for the docs so we can improve on them - see proposal at http://wiki.apache.org/httpd/DocsAnalyticsProposal I'll let this sink in for a few days, and then I will propose a vote for each segment in the order displayed above. If any of you have comments, suggestions, critique, anything, I urge you to please step forward and say so. I dislike the illusion of consensus just because people can't be bothered speaking up until something is actually committed to the repository. As an interim measure, I also think it would be wise to revert the changes applied in r1335029/r1335773, for the time being. We have already voted on adding _a_ commentary system to the documentation, so I'm not going to revert all the blood, sweat and tears that went into integrating a comment section in the docs, but what I can and will is add a JavaScript hack to disable the Disqus commentary system itself while we get this sorted out. Regardless of which method of commenting we eventually settle on, it will still require the same basic structure as is defined at the moment, so I see no point in scrapping all of it, just to reinstate it again. With regards, Daniel.
Re: [Result] Re: [Vote] Add commentary system to httpd docs
On 07.05.2012 16:02, Daniel Gruno wrote: With an impressive 8 x +1 binding votes and no -1's, as well as +2 from other docs@ readers, I believe we can call this vote passed with flying colors :). Apologies for being late with this, but the specifics of the currently used implementation (Disqus) only caught my attention after the Google Analytics trial this week. I very much appreciate the recent work on improving the docs and would by no means want to dampen that enthusiasm. Adding a commentary system also seems like a completely reasonable step to me (provided that the comments are moderated before appearing on the site). Looking at the call for votes [retained below for reference] and at the votes, I'm not sure if the +1 voters were aware of the specific mechanics of the Disqus comment system which is now embedded into all HTML below http://httpd.apache.org/docs/trunk/ [1], however. Effectively, using Disqus means that even visiting an innocent page like http://httpd.apache.org/docs/trunk/license.html will already result in all sorts of drive-by tracking requests [2], among them Google Analytics (pulled in via httpd.disqus.com/thread.js). Based on the fact that there's currently no privacy policy for httpd.apache.org - which would make visitors aware of being tracked (and link to both the Disqus privacy policy [3] and the GA privacy policy [4]) - I believe that the vote should be repeated, with being recast to: [+/-1] Add the Disqus commentary system to the trunk documentation. As an interim measure, I also think it would be wise to revert the changes applied in r1335029/r1335773, for the time being. Kaspar [1] http://svn.apache.org/viewvc?view=revisionrevision=r1335029 [2] URI host names: httpd.disqus.com, www.google-analytics.com, pixel.quantserve.com, b.scorecardresearch.com, juggler.services.disqus.com, mediacdn.disqus.com [3] http://docs.disqus.com/help/30/ (which states, inter alia: This Privacy Policy was first published and made effective on May 9, 2012 - which makes you wonder what they had in place before that date...) [4] http://www.google.com/policies/privacy/ On 04-05-2012 15:58, Daniel Gruno wrote: 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.
[Result] Re: [Vote] Add commentary system to httpd docs
With an impressive 8 x +1 binding votes and no -1's, as well as +2 from other docs@ readers, I believe we can call this vote passed with flying colors :). We will begin rolling out the commentary system in the trunk docs shortly, and then we'll see where the wind of the web takes us. I suspect I'll be following up on this with some discussions on the more specific details of how we should run this comment system later this week, but for now, let's just enjoy it for a few days, and see how it plays out. The current questions we need to discuss can be found at http://wiki.apache.org/httpd/DocsCommentSystem#Questions_for_further_discussion so do give them a read-through and add a question or two if you have any. With regards and humble thanks for your support, Daniel On 04-05-2012 15:58, Daniel Gruno wrote: 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.
Re: [Vote] Add commentary system to httpd docs
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.
Re: [Vote] Add commentary system to httpd docs
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
[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 rbo...@rcbowen.com mailto:rbo...@rcbowen.com :: @rbowen rbo...@apache.org mailto:rbo...@apache.org
Re: [Vote] Add commentary system to httpd docs
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 rbo...@rcbowen.com :: @rbowen rbo...@apache.org
Re: [Vote] Add commentary system to httpd docs
+1 [+/-1] Add commentary system to the trunk documentation.
Re: [Vote] Add commentary system to httpd docs
[+1] Add commentary system to the trunk documentation.
Re: [Vote] Add commentary system to httpd docs
On Friday 04 May 2012, Daniel Gruno wrote: [+/-1] Add commentary system to the trunk documentation. +1
Re: [Vote] Add commentary system to httpd docs
[+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.ga...@brainsware.org URL: http://brainsware.org/ GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
Re: [Vote] Add commentary system to httpd docs
On 5/4/2012 8:58 AM, Daniel Gruno wrote: [+/-1] Add commentary system to the trunk documentation. +1 -- Daniel Ruggeri
Re: [Vote] Add commentary system to httpd docs
[+/-1] Add commentary system to the trunk documentation. +1
Re: [Vote] Add commentary system to httpd docs
On 2012 5 4 15:04, Igor Galić i.ga...@brainsware.org 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 rbo...@rcbowen.com
Re: [Vote] Add commentary system to httpd docs
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