Develop a policy for comment deletion on api.drupal.org

I think having (and enforcing) such a policy will be important for our community.

The main policy document on Commenting on community documentation pages and API pages only deals with adding comments to these pages. It has nothing to say about deleting them.

Often, to really understand how to use the Drupal API, one need to see good examples of correct usage. Such examples are seldom part of the API page itself (automatically generated from the doxygen-like markup in the function's docblock in PHP), but can be found in comments to that page, posted by users who've struggled with understanding the API and figured out a way to do it.

Some of these examples are good, some are bad (i.e. downright wrong), and some are ugly (it may work, but the example is inefficient, redundant, or outdated). There are also comments to the comments, pointing out the problems with previous comments. These meta-comments are a poor solution to the problem, because you need to read though all the comments to figure out what the real solution is. If you're not an experienced developer, you may not even be able to locate the good (as opposed to the bad and the ugly) in these meta-comments.

That more documentation is better, is a misapprehension. People hate reading documentation. In particularly, they hate reading confusing, contradictory, redundant and irrelevant documentation (and a lot of the comments you can find on the Drupal.org API and community documentation pages are at least one of those things).

I've noticed that an increasing number of Drupal developers are turning to Drupal Answers @ Stackexchange instead the Drupal.org to learn about API usage and Drupal site building.

I've nothing against Stackexchange (I use it a lot), but I think our goal should be to make Drupal.org primary resource for Drupal documentation, and one of the things that are stopping us from reaching that goal, is the fact that we do not delete comments that are not helpful.

I hope this can be changed. Not to make it too complicated, just state as a matter of policy, the Documentation group should be tasked with reviewing reports about not helpful comments (posted to its issue queue), and if the comment is indeed found to be not helpful, they can move the issue to the webmaster's queue and request that the comment, and its sub-thread, is deleted.

This one is an example from the community documentation with a lot of non-helpful comments that could do with some cleaning up if can decide on a policy for this.

One thing to keep in mind is that we may need to have different policies/procedures for comments on Drupal.org community documentation pages vs. those that are attached to a page on api.drupal.org.

A couple of my initial thoughts on this.

We should treat comments like temporary post-it notes on a piece of documentation that serve to help inform ways that the documentation itself might be improved. These notes should all be considered transient and removed once they have fulfilled their purpose. With the understanding that that may not always happen given the high volume of comments and relatively low number of people helping to moderate them.

It makes sense to ensure that people are comfortable deleting anything that is SPAM, and things that are overly self promotional. Example: https://www.drupal.org/node/1089656#comment-8860609

On api.drupal.org, comments that correct the documentation should be converted to issues to get the documentation updated, and then removed once the documentation is up-to-date.

Comments that correct, or improve upon, the community documentation should be rolled in to the page and then removed.

Simple compliments like, "+1 this comment is good", or criticisms that don't add anything relevant to the conversation like, "This reply is stupid.". Should probably be removed.

I've also added this to the agenda for the next documentation working group meeting so that we can make sure and talk about this more then too.

This isn't something that I've had to deal with before personally so I'm loving the suggestions provided already. Does anyone have links to good examples of this kind of policy elsewhere? The first placed I looked was PHP, which has a little bit, but not a lot, related to removing comments displayed when you're about to post a comment. http://php.net/manual/add-note.php?sect=function.strstr&redirect=http://...

I think the StackExchange policy on comments: http://meta.stackexchange.com/questions/19756/how-do-comments-work is worth a look.

Deleting comments would be a huge mistake and would reduce trust. Just add a note if you see something you think is wrong. The person you replied to might point out how you're wrong.

On Stack Exchange sites, they are more restrictive about comments, since they are Q&A sites, while api.drupal.org is a documentation site. They are different type of sites with different necessities.

On the bottom of any page that documents a class/function/method/constant, there is the following text.

Buggy or inaccurate documentation? Please file an issue instead of commenting here. Need support? Need help programming? Connect with the Drupal community.

I would delete comments asking for support and comments pointing out something that is wrong in the documentation, as the comment form already suggests what it should be done instead of posting a comment on api.drupal.org. I would also deleted those Thank you comments, as Stack Exchange sites do.
I would not delete comments containing example code (including the ones with wrong code), except in the case there are too much comments about that example code (especially when they are old comments). Comments on api.drupal.org have never be supposed to be for extended discussions (which is also true for Stack Exchange comments); if there is an useful discussion about the appropriate code to use, that should go in a more appropriate place, where it gets more visibility (which is useful for Drupal beginner users).

Since api.d.o does not allow to log in, and comments from anonymous users are not allowed, this issue can be postponed to when comments will be enabled again (if they will be enabled).

I am closing this issue basing on #2714191: Remove comments logic: Comments will not be re-enabled on api.drupal.org.