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.

Issue reports are the primary tool by which handbook updates are tracked. Always include the node number or URL.

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

See Bug reports for documentation on submitting issues against modules. See Embedded documentation for submitting issues on the built-in help text.

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 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.
• Avoid "active (needs more info);" issues with this status are not displayed in the default filter and are not distributed on the mail list (neither are issues updated to "duplicate," "won't fix," "by design," and "closed").

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.