API page: http://api.drupal.org/api/drupal/modules%21system%21system.api.php/funct...

The following comment http://api.drupal.org/comment/47683#comment-47683 (disable "Request new password by monymirza) is wrong and should be removed (along with the comments from jimurl and myself pointing this out). Grounds for removal:

  • It doesn't make sense, as this menu item in only shown for the anonymous user.
  • hook_menu_alter doesn't run every time the menu loaded. It only runs when the cache is rebuilt and a few other times. I.e. you can't have logic in it, only a constant value or a callback.
  • The reference to $user->id is a typo (should be $user->uid).

It doesn't work, and it even gives the casual reader the wrong idea about how to use this hook, and should therefore be removed.

Comments

jhodgdon’s picture

Title: Buggy example for hook_menu_alter » (comment moderation) Buggy example for hook_menu_alter
Project: Drupal core » Drupal.org site moderators
Version: 7.x-dev »
Component: documentation » API.drupal.org
Category: bug » task

I agree that the example is quite wrong. But I'm not sure that we have a policy of removing comments with incorrect code in them. Actually, having an incorrect example followed by replies that state why it is wrong can be kind of instructive at times. It would have been better if you had actually replied to the comment (so that the reply would be shown indented and it would be more obvious that it was a reply)...

Anyway, referring to webmaster group for decision. I'm just not sure what the comment moderators on api.drupal.org are doing in cases like this currently.

jhodgdon’s picture

I forgot, we do have this policy document:
http://drupal.org/node/14345
but that only says what to do if you find a problem in the *documentation*, not a problem in a comment.

And the original reporter here started a discussion on groups.drupal.org to see if we need a webmasters policy document:
http://groups.drupal.org/node/297408

apaderno’s picture

Project: Drupal.org site moderators » API.Drupal.org customizations
Version: » 6.x-3.x-dev
Component: API.drupal.org » Documentation
Issue summary: View changes
jhodgdon’s picture

Project: API.Drupal.org customizations » Drupal.org site moderators
Version: 6.x-3.x-dev »
Component: Documentation » Other

What is our policy for removing comments on api.drupal.org? I do not know where such a policy is, who's monitoring comments there, etc. This comment that is requested to be removed is not spam, it is merely incorrect.

That is why I moved this to the webmaster queue.

Moving back (sorry!) until someone can point out the policy.

gisle’s picture

AFAIK, no policy for curating comments exists.

I believe we should have one, and that the group that should be tasked with creating such a policy is the documentation group.

Without curating of contents, including comments, documentation on Drupal.or will be hard to use for inexperienced users, who will be unable to distinguish between incorrect and correct information.

While the documentation working group should not go out there and look for erroneous comments, they should respond to reports about errors and remove those found to be misleading.

apaderno’s picture

We have Commenting on community documentation pages and API pages, where nothing is said about wrong example code given in comments that are not support requests. It just says that the following are allowed comments for the documentation pages:

  • Providing links to modules, blogs, and relevant articles.
  • Links to forum posts and Handbook pages with information directly related to the API page.
  • Usage examples (e.g. boilerplate code snippets showing how to make use use of the API).

I take that with wrong examples, you can just comment saying they are wrong, and point out where they are wrong, without starting a long discussion.

When I delete comments on API.Drupal.org, I delete supports requests and thanks comments; in some cases, I delete those comments that merely copy-paste part of the API document, without adding anything else.

I apologize for moving the issue: We are removing some of the issue components, and the directions were to move questions about the API sub-domain to its issue queue.

gisle’s picture

Status: Active » Fixed

I just noticed that this one has been fixed!

A some point in time between now and May 5th, 2013, somebody took it upon themselves to remove the comment with the buggy code. My thanks to whoever it was who did it (even if there exists no policy for removing comments on the API with code-examples that are simply wrong.)

I still think it would be better if we had a policy for this, complete with transparent procedures for reporting errors, review of errors and removal of those found to be buggy. However, nobody has happened to that initiative in two years, so I not going to pursue it further.

tvn’s picture

Since this is not the first time this type of request comes to Webmasters, I opened a follow up issue #2515002: Develop a policy for comment deletion on api.drupal.org and will ask DocsWG to take a look at it.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.