Documentation commentary system
This document describes the proposed changes to the Apache HTTP Server documentation, in which a commentary system will be added, thus enabling people to comment on (almost) every page in the documentation.
The reasons for wanting to add comments to the system are plenty:
- As a means to offer feedback on the document
- As a means to offer examples, bug reports, and grammatical fixes.
- As a means to tell us what's missing from the document, or ask questions, or what not.
- As a possible means of recruiting new committers and general contributors by lowering the bar for contributing to the documentation effort
The currently proposed solution is to use a new comment system developed for the Apache Software Foundation.
This system is now hosted on ASF hardware at https://comments.apache.org
The backend system itself is run by Lua scripts on Apache 2.4 with mod_pLua and a MySQL database. Source codes are located in the infra repository.
Which pages can be commented
The comment system will be available for all how-to guides and module pages. All index pages, quick references and the likes will not have the comment system attached to them. Furthermore, the comment system will not be available in the CHM or zipped versions (WAR?) of the documentation.
Each branch (2.2, 2.4 and trunk) will have its own separate comments. We may choose to copy or move comments from one branch to another, and if this is deemed necessary, a plugin for the comment system will be set up to allow for easy movement between branches.
The various translations will, together with the English version, share the same discussions. Threads will be based on the page that is being shown, not the language it is being shown in. Comments about translations (typos etc) will be tolerated, but all other communication should be in English, so we have a better chance of moderating and following up on comments.
Comments will, in general, be allowed through without pre-approval. Comments with hyperlinks in them will require approval from a moderator before they are shown on the site. The comment system itself has a built-in Turing test that should get rid of most of the spam (we have yet to receive any spam).
Any Apache committer that wishes to become moderator can do so by logging onto the comment system (see the "log in" link in each comment section) using their Apache committer id and password. Since this will be managed by the LDAP service, any new committers will automatically gain this right without any previous manual work done by the sysadmins.
One or more key figures will be appointed comment administrators, and may use this role to manage/verify non-Apache people that wish to become moderators.
Verified people or moderators will have their comments flagged with a small feather to show that their identity has been verified by Apache.
Moderators and admins can click on the "moderate" link in a comment section to go to the moderator panel of the system, where they can review the latest activity, track specific poster origins and perform tasks such as removing all posts made from a specific poster or ban an IP/origin from posting on this site or any other that uses the comment system. Comment admins can furthermore review activity logs to see if any moderator or poster has been behaving strangely, and act accordingly.
Comments in offline documents
For security reasons, user friendliness and other browser quirkiness issues, the comments will not be available for viewing when viewing the documentation from any other place than httpd.a.o.
The comment system supports an XML export of comments (which can be found here). At this time, there doesn't seem to be any pressing need for this, but it's there should we need it.
Questions for further discussion
There are no outstanding questions. If you have one, please add it.