Documentation issue reports

This page is primarily to:

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

The documentation issues page is the primary tool by which handbook updates are tracked. When reporting an issue with a handbook page, always include the page's URL or node number.

Issues vs. e-mails: It is usually better to submit issues than sending e-mail directly to the documentation list for most matters, including any topic that requests response or action. That way, the topic becomes a node, and can be more easily followed. For requests to join the documentation team, proposals, and similar discussions, label the issue report with category: "support request," and status: "active."

To report an issue with a module's documentation, see bug reports. To report an issue with the Drupal software's built-in help text, see embedded documentation.

Issue report project:

• Use "Documentation" for most handbook documentation issues.
• Use "Drupal.org webmasters" for page delete requests, such as spam and test handbook pages.

Issue report component:

• Correction/Clarification:
  This is for existing documentation. If documentation is unclear or wrong, please choose this component. For example, content is actually wrong and needs to be updated or something is just blatantly confusing.
• New Documentation:
  If you have suggestions about adding documentation, either sections or content, please use this component.
• Placement and Navigation:
  Content should be moved to a different section because it would be more relevant there.
• Delete Comments:
  This is for informing about the action of rolling in comments in Drupal Handbooks that needs to be deleted if you are not a Site Maintainer so has to complete your contribution.
• Outdated:
  If content is outdated and does not apply or should be found under a different section/archive, use this component.
• Vandalism/Spam:
  If content or comments are vulgar or Spam, let us know by using this component.
• Become a documentation admin:
  See Apply to be a doc admin
• Other Documentation Issues:
  If for some reason, your issues does not fall into the preceding component categories, please use this one.

Issue report category:

• Use "bug report" for errors.
• Use "feature request" for requests, including new material and policy changes.
• Use "tasks" when an update is in development.
• Use "support requests" for requests that require site administrator role, including joining the documentation team, deleting handbook page comments that have been incorporated, and adjusting page weight for proper page ordering.

Issue report status:

• Use "active" for feature requests and bug reports for which the solution is unknown.
• Use "patch (code needs work)" if ideas or a proposal or rough draft are being hashed out.
• Use "patch (code needs review)" if you've attached or posted a page you would like reviewed.
• Use "duplicate" if the issue is a duplicate of another issue that already exists (see more below).
• Use "fixed" when the item is completed; its status will update to "closed" automatically in two weeks.
• These statuses are not displayed in the default filter and are not distributed on the mailing list.
• Avoid "active (needs more info)"
• Use "duplicate" and leave a reference comment.
• Avoid "won't fix" and "by design" as these do not address the issues main objective. It is prefered to comment why this issue is no longer valid and mark as "fixed".
• Dont set items as "closed". Doing so will generally receive negative feedback from the original poster and others. Instead use the status "fixed".

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 for flagging issues. You are encouraged to add these tags to your issue, if applicable:

• locked: The page is locked for editing by regular drupal.org users
• locked to admins: The page is even locked for editing by members of the Documentation Admin group
• embed image: This is a request to embed an image into a page (which requires doc admin privileges to accomplish)
• table needed: This is a request to convert part of the page into a table (which requires doc admin privileges to accomplish)
• graphic needed: This issue involves editing an existing image or creating a new graphic to illustrate something (which requires graphical editing tools and expertise)
• You can also add new tags along the lines of "embed image" and "table needed" so that people viewing your issue can get a quick idea of what needs to be done. However, if the task is already covered by choosing a Component (such as "delete comments") there is no reason to duplicate this information by also adding a tag.

Issue report style guide:

• The "problem" is that the tab character will show up in the message which is e-mailed, but not on the node created at drupal.org. Conversely, using html tags like ul (unordered list) show up on the issue report at drupal.org, but are lost (nested list looks flat) in the plain text e-mailed out to the documentation list.
• "Reorganizing the Patch docs" is an excellent example of this, as the same text was sent out both ways. Compare the issue node and the mail list output. The first submission worked on the mailing list; the second one worked on the on-line issue report; neither worked on both.
• The "solution" is to use generally plain text formatting without leading spaces and tabs.
• For indents and lists, use two hyphens "--" to denote hierarchy. This has the advantage of being consistent with the drop-down "parent" field for pages in the handbooks. Avoid using ordered or unordered lists, <ol> and <ul>.
• Hyperlinks are fine: they function at the issue report node, and are converted to footnotes in the e-mail. You only need the short path, such as <a href="/node/999">.
• Bold tags (<b>) are delimited with asterisks "*" in the e-mail version.
• Italics tags (<i>) are delimited with slashes "/" in the e-mail version.

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.

Duplicate issues: If an already-created issue turns out to duplicate another issue, update its status as "duplicate" and reference the issue kept. Keep the issue that is older, or has unique additional information like a patch, or already assigned. After being marked as "duplicate," an issue should then be updated to "fixed" by the person assigned to it, the originator, or someone else, after verifying that it is a duplicate. A "duplicate" issue does not automatically update to "closed" like a "fixed" issue.

Attachments should be used for large write-ups to help reduce the length of the list e-mails, and when substantial html markup is used.

"@username:" is often used in an issue update to indicate response to a particular person's earlier comment.

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

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