This is an old revision of the document!

Revamping user comments at

Possible mentor: Philip Olson

This task involves rethinking how we handle user comments at This is mainly (only, currently) done within the PHP manual but it could leak into other areas like at

The first task involves defining what a user note is (or should be). Is an example that happens to use strlen() a fine user note for the strlen() documentation? Are examples even appropriate user notes? Is the current moderation system working? Many other questions will arise.


There has been some discussion.



Baby steps: step A, moderation flags

This involves a simple user notes moderation flag option. Users can flag notes as “bad”, which prompts a moderator to look into it. Users do not need to login, but if not logged in, must answer a recaptcha or similar.

How it will probably work
  1. User clicks on “flag” button near individual note
  2. Popup
    1. Checks if logged in
    2. If not logged in, prompts reCaptcha or similar (human?)
  3. Window now has several options, including:
    1. A button to submit the flag, with no details (quick flag)
    2. Or optionally allow entering details such as name, email, textarea and/or select reason for flag (e.g., Spam)
  4. Flagged notes generate email to a list, and are also listed within our web admin panel. (only email for now is fine)
    1. People can subscribe to receive these emails? (future)
  5. Moderator takes action, which includes current options (delete/reject/modify) and perhaps a new unflag option.
  6. If note flag is accepted (e.g., deleted), should we notify the user via email? Or list via email?

Notes about the current system

The current system was written in the 90's, and contains files spread out in several places throughout the PHP project. Also, various note moderation statistics are listed here.


Revamping Tactics

Currently the user comments system introduces a number of a fundamental problems that inhibit both its use as well as its usefulness. This section aims to address many of those existing problems and the tactical approach to hopefully weeding them out and setting the new system on a more manageable future course.

Here is an incomplete list of some of the issues I'll be attempting to tackle first.

  1. The importance of what data is stored and how that data can later be used needs to be addressed head-on. The current database schema in the master database allows for a number of useful options to further advance this system to the next step (such as votes, and rating). However, this schema makes these particular pieces of information in the database difficult to work with. For example, it can not be easily implemented in a manner that allows us to store individual votes or ratings on a per user bases in its existing form. This would require a second table for storing individual rows that can be indexed and joined to the note table for collecting such information in a more fine-grained manner.
  2. The ability for the user to flag certain comments is key in the moderation step. There aren't nearly as many moderators with access to the moderation system as there are users. However, any information collected from the user needs to be useful to an autonomous system as well as a human. Cutting back on tedious human moderation is vital in fighting spam and other abusive behavior. This would entail that the user should not be able to simply flag a comment without offering up an actual reason. Flagging a comment without intent presents the obvious problem of a human still having to decide why this comment should be moderated or removed. If we can alleviate the human factor and narrow down information that allows the human to make a quick and intelligent decision based on the available information we can expedite the moderation process.
  3. Presenting the information in the user-submitted comments to the user in a more meaningful and useful manner can also play an important role in allow, encouraging, and enabling the power of a community to unanimously decide on what is considered more or less valuable. Currently the system only presents the comments in a descending order by date. This allows the more current comments to remain at the top. While this is a good idea, it's also not the best idea. Some improvements may including using multiple criteria for ordering and presenting comments to the user, such as rating, votes, and dates with optional sorting fields (descending/ascending).
ideas/usercomments.1342860423.txt.gz · Last modified: 2017/09/22 13:28 (external edit)