Commenting on handbook pages and API pages

Commenting on Handbook pages or API pages is when you use the "Add new comment" button to post a comment, or "reply" to an existing comment, when viewing a Handbook page or a page on the api.drupal.org API documentation site.

In general, the preferred method of correcting an issue with a Handbook page is to simply use the "edit" tab on the top of the page. If the "edit" tab does not exist you may submit an issue with category "bug report." The best method for requesting missing documentation is to submit an issue with category "feature request." The documentation team has limited resources, and handbook page comments are lower in priority than submitted issues.

If you find an problem with an API documentation page, you should submit an issue against the Drupal project, using component "documentation" and category "bug report".

If you have a question about how to use a function or do a task described, please use the Forums or one of the other Support options, rather than adding a comment.

Please read the following points carefully before adding comments to Handbook and API pages. We try to keep the handbook clean and up to date, and the API documentation complete, but with a limited pool of volunteers this tends to happen in batches.

Valid handbook and API documentation comments:

• Providing links to modules, blogs, and relevant articles.
• Links to forum posts with new information directly related to the handbook or API page.
• Links to similar content in the handbook, or links to inconsistent content in the handbook.
• Comments that provide useful facts that should be included in the handbook page.
• Noting errors in the documentation or corrections to incomplete information.
• Complete re-writes of the handbook page.
• Content that should become a child page of a handbook page.
• Noting dead links.
• Terminology recommendations, including inconsistencies and terms which new users may be unfamiliar.
• Suggestions to clarify text for new users.
• Recommended re-organizations and outlines of handbook pages or handbook sections.

If you can follow up your comment with a bug report, that would be helpful. Please note that when your comments are incorporated into the documentation, your comments will be removed.

Comments are hard to maintain and often confuse readers; thus, the following kinds of comments are discouraged:

Bad handbook comments:

• Requests to change Drupal modules, including Bug reports, feature requests or language changes.
• Identifying that a topic is not documented. Such requests should be submitted as bug reports with category "feature request."
• Documentation feature requests. Again, these are better submitted as bug reports with category "feature request."
• Support questions. If you need to ask a question, use the forums or the drupal-support list, or see what other support options are available. Support requests in the handbook are removed.
• Questions about the meaning on a page. These are really support questions. The best process is to probably post a question in the appropriate support forum asking for help on what the documentation page means, then once you've solved the issue, submit a bug report against the page proposing an update.
• Links to external content. If the content provided on external sites is important, it should be incorporated into the documentation, not linked to.

If you post a "Bad" comment in the handbook or API pages, it will be edited or removed.