Commenting on handbook pages

Commenting on Handbook pages is when you use the "Add new comment" button to post a comment, or "reply" to an existing comment.

In general, the preferred method for reporting handbook problems is to 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.

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

Valid handbook comments:

• Providing links to modules, blogs, and relevant articles.
• Links to forum posts with new information directly related to the handbook 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.

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