Last updated February 1, 2012.
There are currently two Drupal documentation sites: the API Documentation (programming reference) at http://api.drupal.org and the Community Documentation (pages created by the Drupal community) at http://drupal.org/documentation. They have different styles of commenting.
In all cases though... if you have a question about how to use a function or perform a task being described, please use the Forums or one of the other Support options, rather than adding a comment. And if you want to report a software bug, file an issue instead of adding a comment somewhere.
API documentation comments
The API documentation pages themselves are generated from specially-formatted comments in the code, and generally are limited to documenting the behavior of the function (or constant, class, etc.), and its parameters and return value. Comments are used to provide examples and other information. Valid API documentation comments:
- 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
If you find an problem with an API documentation page (incorrect or incomplete documentation), instead of adding a comment, use the "File an issue" link above the comment form to create an issue in the Drupal Core project, in component Documentation.
Community Documentation comments
If you find some content in a Community Documentation page that is incorrect or needs clarification or updating, the best response is to click "Edit" and fix the page.
If there is no Edit link, the page is "locked for editing"; follow theses steps to get it unlocked, and meanwhile, add a comment explaining what needs to be fixed on the page.
If you don't have time to make the needed edits, add a comment to the page explaining the problem, and click Edit to change the page status to "needs copy/style review", "needs technical review", or another appropriate status. This will allow people to use the Documentation management and status page to find this page when they are in the mood to do some editing.
If what is needed is a completely new page of documentation, click "Add child page" at the bottom of the page, and write the documentation. If all you have time to do is outline what needs to be done, do that and mark the status as "incomplete".