Last updated October 30, 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.

Introduction: Projects and issues

The Drupal Project as a whole is composed of a large number of "projects", which are basically working groups. The central project, "Drupal Core", is dedicated to maintaining the Drupal Core software; there is also a project for each contributed module, theme, and installation profile that you can download on Drupal.org. Each project has a project page, where you can download that project's software product. And for tracking bugs, feature requests, and other issues related to that project, each project has an "issue queue". For instance, the Drupal Core project page is http://drupal.org/project/drupal, and its issue queue is located at http://drupal.org/project/issues/drupal .

The Documentation Team also has a "project" associated with it. It's not exactly like other projects, because the Documentation Team writes documentation for many other projects, and doesn't have a zip file you can download. But the Documentation project does have an issue page, which is located at http://drupal.org/project/issues/documentation. This page describes what the Documentation Team uses issues for, and how to report problems with Drupal documentation.

What to report in a Documentation issue

You can use a Documentation project Issue to report:

  • A page that you don't have permission to edit (request that the page be unlocked so that you can edit it to fix the problem).
  • A major content problem, such as that a whole page or section needs to be updated for a new version of Drupal and the current text is completely unusable for the new version. (For minor problems, don't use an issue. The best solution is to edit the page directly, and the second best is to add a comment explaining the problem, and then edit the page to change the Page Status to "needs technical review" or another appropriate status.)
  • A request for new documentation to be created that you don't know how to write. (It is preferable, if possible, to 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 inappropriate content (however, spam should be reported to the Drupal.org webmasters).
  • 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 effort. In this case, they should choose an issue tag for their effort (see list below or create a new tag in the list if appropriate), and make sure to tag all their issues with that tag.

Creating an issue (choosing a project)

To construct an issue report, you will complete an issue form. It is possible to create an issue by visiting http://drupal.org/node/add/project-issue; if you do that, the first thing you'll have to do is to choose a project. With literally thousands of projects to choose from, you will probably find it easier to use one of the links below (which will pre-select the project).

If you have found an problem with...

  • Spam:
    Use project "Drupal.org webmasters" for spam reporting, and fill in the following fields:
    • Category: task
    • Component: Spam
    • Title: Spam from [username] on [page]
    • Body: Include a link to the page or comment that contains the spam, and include the spammer's username.
  • Module or Theme documentation:
    If the issue pertains to a particular contributed module or theme's documentation, choose the project for that module or theme. It's easiest to start by visiting the module or theme's project page, find the Issues link in the right sidebar, to arrive at the project's issue list. Search first to see if the issue is already reported, and if not, click the "Create new issue" link, and fill in the following information:
    • Category: bug report
    • Component: Documentation
    • Title/Body: Describe the problem you have found clearly
  • API documentation on api.drupal.org:
    Use project "Drupal core" for issues related to the API documentation on api.drupal.org. The easiest way to create an issue is to click the "Create an issue" link on the api.drupal.org page that has the documentation problem. That will fill in most of the issue fields for you, and you'll just need to add a description of what the problem is to the title and body fields.
  • Help text for Drupal's core functionality:
    Use project "Drupal core" for issues with Help text within a Drupal installation's core functionality, and fill in the following fields:
    • Category: bug report
    • Component: Choose the core module whose help has the problem
    • Title/Body: Describe the specific problem you noticed
  • Drupal.org online Community documentation:
    Use issue queue "Documentation" for issues related to the Drupal.org online Community documentation, and fill in fields as detailed below.

Documentation issue report fields

For reports to the Documentation issue queue, the following sections show what to put in each issue field.

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.

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 "Support" in the Drupal.org header area to find better support options.

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.

Title and Body/Description

  • Compose a good title that describes the problem in one line.
  • 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">.

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.

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.