Documentation issue reports

Last updated February 6, 2012.

This page is primarily to:

Aid documentation contributors in submitting effective issue reports.
Introduce the issue report system to those new to it.

You may also be interested in this video on how to use the Drupal issue queues to contribute to Drupal, and this page on fixing and responding to issues.

What to report

The documentation issues page is used to track problems with online Community Documentation pages. Only use an Issue to report:

A major issue (for minor issues, either edit the page directly, or add a comment and then edit to change the Page Status to "needs technical review" or another appropriate status).
An issue with a page that you don't have permission to edit (request that the page be unlocked).
A request for new documentation to be created (or you can just create the documentation yourself by clicking Add Child Page at the bottom of the page where you want to add documentation).
A request for comments to be deleted, after you have incorporated them into the text of the page.
A report of spam or inappropriate content.
A group of people working on a specific set of new or improved documentation can also use an issue or issues in the Documentation project to discuss their project. In this case, they should choose an issue tag for their project (see list below or create a new tag in the list if appropriate), and make sure to tag all their issues with that tag.

Constructing a good issue report

Visit http://drupal.org/node/add/project-issue to start an issue report. Then follow the guide below to fill it in.

Issue report: Project

Use "Drupal.org webmasters" for spam reporting. Information below does not apply -- choose component "spam" and category "task", and be clear about which page or comment is spam.
If the issue pertains to a particular contributed module or theme's documentation, choose that module or theme as the project. Information below does not apply -- choose component "documentation", and describe the problem clearly.
Use "Drupal core" for issues related to the API documentation on api.drupal.org. Information below does not apply -- choose component "documentation", and link to the page on api.drupal.org that has the problem.
Use "Drupal core" for issues with Help text within a Drupal installation's core functionality. Information below does not apply -- choose the core module whose help is incorrect as the component.
Use "Documentation" for issues related to the Drupal.org online Community documentation. Information below applies -- read on!

Issue report: Component

Correction/Clarification:
This is for existing documentation. If documentation is unclear or wrong, choose this component. For example, content is actually wrong and needs to be updated or something is just blatantly confusing. Better yet, just edit the page instead of filing an issue, or add a comment to the page explaining what needs to be fixed, and edit the page to change the Page Status to "needs technical review" or another appropriate status.
Missing Documentation:
If you have suggestions about adding documentation that is currently missing, either sections or content, use this component.
Placement/Navigation/Structure:
Content should be moved to a different section because it would be more relevant there, or pages should be split up or combined. Better yet, just go ahead and make the change.
Manage Comments:
Comments have been incorporated into the text of the page, or they are not useful, and they need to be deleted.
Vandalism/Spam:
Use this component and link to the page(s) defaced. But if something is blatant spam (such as adding a comment with links to a fake watch site), report it in the Drupal.org webmasters project instead).
Docs infrastructure:
If you have suggestions on how to improve drupal.org's infrastructure in relation to the documentation process.
Unlock pages:
See Pages locked to editing
Other Documentation Issues:
If for some reason, your issues does not fall into the preceding component categories, use this one.
API documentation files:
Issues related to the API documentation files, such as the Form API reference, that are managed in the Documentation project.

Issue report: Category

Use "bug report" for errors on pages (factual, style, etc.).
Use "feature request" for requests for new documentation and policy changes.
Use "task" for a task request, such as deleting comments from a page.
Do not use "support request". If you have a support question, click on "Community and Support" in the Drupal.org header area to find better support options.

Issue report: Status

Use "active" for feature requests and bug reports for which the solution is completely unknown or work hasn't started.
Use "needs work" if some ideas are there, or a proposal or rough draft are being hashed out.
Use "needs review" if you've attached or posted a page you would like reviewed.
See the Fixing and responding to issues page for ideas on how to change the status of an existing issue.

Issue report Body of report

Be sure to include the URL of the page you are discussing in the issue! Otherwise, no one will be able to figure out what you are talking about.
Use "code" tags (<code>) around any code you post, so that the full HTML shows on the saved issue.
For indents and lists, you can use ul and li tags two hyphens "--" to denote hierarchy. This has the advantage of being consistent with the drop-down "parent" field for pages in the handbooks.
For links to other Drupal.org pages, you only need the short path, such as <a href="/node/999">.

Issue report: Tags

Issues on drupal.org can be tagged by using the Tags section at the bottom of the Issue report form. The Documentation group uses the following standard tags. You are encouraged to add these tags to your issue, if applicable (please don't make up your own tags):

d7docs: Priority issues relating to the Drupal 7 documentation. These issues focus around docs that are integral to installing and running Drupal 7.
developer: Issues dealing with developer focused docs.
distributions: Issues dealing with the different Drupal distributions.
docs admins: Issues that needs the attention of the admins.
docs infrastructure: Infrastructure/code improvements related to documentation.
fapi reference: The Drupal Form API reference should be updated.
git: Docs related to installing/using git or the git migration.
graphic needed: This issue involves editing an existing image or creating a new graphic to illustrate something (which requires graphical editing tools and expertise)
locked: The page is locked for editing by regular drupal.org users
novice: These issues have a low barrier to entry for users new to the Drupal documentation process. Issues can cover any topic related to the docs and require minimal technical knowledge.
server stuff: Any issues dealing with the server aspects of Drupal. Including but not limited to installing/configuring/debugging Apache, Mysql, Postgresql, etc...
testing: For issues related to the testing/simpletest documentation.
theming: A Theming guide page should be added or updated.
valid issue: Issues that have been reviewed and cleaned up according to http://drupal.org/node/1204344 and are ready for someone to work on

Other considerations

Discussion amongst the documentation maintainers (via an issue report) should be pursued prior to performing the following types of changes:

Changing the name of a top level chapter in one of the books.
Moving a top level chapter in a book.
Large re-writes.
Big re-organizations.
Rough drafts that are not yet ready for production.

Look at existing issues to verify that the topic is not already filed. Reference potentially-related issues. If a forum discussion is the genesis of an issue submission, reference it.

"@username:" is often used in an issue update to indicate response to a particular person's earlier comment (or you can include the comment number).

"+1" and "-1" are used by contributors to indicate a vote of support or recommendation against a proposed update.

Enable the personal contact form in your user account so that documentation team members can contact you about your issue submission.