Commenting on community documentation pages and API pages

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 (e.g. boilerplate code snippets showing how to make use use of the API).

If anything in the generated information is wrong, it need to be corrected at the source level. If you find an problem with a generated 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 these 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. Also please file an issue in the Documentation project -- use the "Report to Moderator" link at the bottom of the page, and change the category and status appropriately, and explain what needs to be fixed.

You can also help by incorporating any comments yourself. See this page for guidelines for incorporating comments.

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".

Closing comments

If comments on a particular page are becoming a problem, the Documentation Working Group may decide to close comments on the page. If you feel that this should be done for a particular page, contact us and let us know.