About Drupal documentation

Creating pages in the Drupal handbooks

Everyone in the Drupal community is invited to submit new pages in the Drupal handbook. Join the documentation team to edit existing pages.

• Please review first the authoring guidelines section for handbook pages.
• Any drupal.org site member may create book pages and edit book pages which they have created. New pages will be reviewed and if need be edited, incorporated into existing content or moved.
• Since regular drupal.org accounts cannot edit book pages which they did not create, additions to or corrections of other handbook pages should be submitted as an issue to the Documentation project.
• Members of the documentation team who are site maintainers may choose to post new pages or edited pages directly.
• Rough drafts of new pages or edited pages which are not production ready--i.e., need feedback and/or additional development--should first be submitted as an issue to the Documentation project.
• Finally, make sure you have enabled the personal contact form in your user account in case Drupal documentation team members need to contact you about your contribution.

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.

Commenting on handbook pages

Commenting on Handbook pages is when you use the "Add new comment" button to post a comment, or "reply" to an existing comment.

In general, the preferred method for reporting handbook problems is to submit an issue with category "bug report." The best method for requesting missing documentation is to submit an issue with category "feature request."

The documentation team has limited resources, and handbook page comments are lower in priority than submitted issues.

Please read the following points carefully before adding comments to Handbook pages. We try to keep the handbook clean and up to date, but with a limited pool of volunteers this tends to happen in batches.

Valid handbook comments:

• Providing links to modules, blogs, and relevant articles.
• Links to forum posts with new information directly related to the handbook page.
• Links to similar content in the handbook, or links to inconsistent content in the handbook.
• Comments that provide useful facts that should be included in the handbook page.
• Noting errors in the documentation or corrections to incomplete information.
• Complete re-writes of the handbook page.
• Content that should become a child page of a handbook page.
• Noting dead links.
• Terminology recommendations, including inconsistencies and terms which new users may be unfamiliar.
• Suggestions to clarify text for new users.
• Recommended re-organizations and outlines of handbook pages or handbook sections.

If you can follow up your comment with a bug report, that would be helpful. Please note that when your comments are incorporated into the documentation, your comments will be removed.

Comments are hard to maintain and often confuse readers; thus, the following kinds of comments are discouraged:

Bad handbook comments:

• Requests to change Drupal modules, including Bug reports, feature requests or language changes.
• Identifying that a topic is not documented. Such requests should be submitted as bug reports with category "feature request."
• Documentation feature requests. Again, these are better submitted as bug reports with category "feature request."
• Support questions. If you need to ask a question, use the forums or the drupal-support list, or see what other support options are available. Support requests in the handbook are removed.
• Questions about the meaning on a page. These are really support questions. The best process is to probably post a question in the appropriate support forum asking for help on what the documentation page means, then once you've solved the issue, submit a bug report against the page proposing an update.

If you post a "Bad" comment in the handbook pages, it will be edited or removed.

Embedded documentation

Every Drupal website contains administrative documentation links embedded into its pages and modules. This documentation is very important to get correct because it lives with the Drupal installation and cannot be changed once the core version is frozen for distribution. The editable version of the embedded documentation is maintained here on drupal.org in the modules section of the Handbook, and on the introductory page of each core and contributed module.

During feature freeze of each new major Drupal release, the Documentation Team updates the module pages in the handbook so that the help is consistent with the latest Drupal version. Once the wording is correct, the embedded doc pages are then rolled into Core. This process is described in more detail on the following pages: [Insert links to detail pages here.]

Getting started:

1. Familiarize yourself with the documentation Handbook Style Guide. This guide should be treated as the overarching law related to all written text.
2. Prepare yourself for working with embedded docs by reading the Embedded Documentation style guidelines. You should write embedded docs with these guidelines in mind since all submitted documentation will be reviewed for compliance with these two guidelines.
3. Study the established format by reviewing several module pages .

The documentation team and the Drupal developers have decided that the format of module pages and administrative help docs need to be short and scannable. If you would like to know more about why users scan web documentation instead of reading it fully, review the Why Users Scan Instead Of Read article on Jakob Nielsen's site.

Handbook style guide

A style guide provides consistency throughout the handbooks, just as Coding standards do for the modules. It offers guidelines for individual page structure, formatting, and markup, as well as language usage, such as italicizing, bolding, spelling, and capitalization. Also see the Documentation writer's guide for overall handbook considerations, such as organization and structure.

All pages, submissions, and edits in the Handbook must follow the following guidelines. Updates to the Handbooks submitted to the moderation queue will not be published until they follow these guidelines.

1. Titles
2. 1. Use short descriptive titles to label a handbook entry. Titles should be 80 characters or less. Avoid redundancy; the words "Drupal" and "Handbook" should rarely be used in titles.
   2. Capitalize only the first letter of a title unless using a proper noun. e.g.: Installing modules; Designing themes in Dreamweaver.
   3. Use "HOWTO: {title}" for documentation pages that function as step-by-step recipe-type howto-style tutorials.
   4. Avoid numbering child pages; use page weight to properly order them. Use "1." style numbering if you must, not "1)" or "1-"
3. Writing style
4. 1. Avoid using personal pronouns: I, my, we, our, etc.
   2. Don't be wordy or colloquial.
   3. Use a single space after a period.
   4. Spell check.
5. Spelling and capitalization
6. 1. Use American spelling. For example, color, not colour.
   2. Drupal, not drupal
   3. e-mail, not email
   4. HTML, not html
   5. URL, not url
   6. PHP, not php
   7. MySQL
   8. JavaScript
7. Paths
8. 1. When describing how to get to a specific user interface option (e.g. the add vocabulary option in the categories section of the administer screen) demarcate the path needed to access the option using this format:
      
      destination (<em>path > to > item > destination</em>)
      Which will yield text that looks like this:
      destination (path > to > item > destination)
   2. Do not abbreviate words in the navigation path (e.g.: use administer instead of admin).
   3. Menu items can move. Include the path for any user interface option.
9. HTML and code formatting
10. 1. Avoid heading tags: <h1>, <h2>, <h3>, <h4>, etc.
    2. Avoid underline <u>; use emphasis <em> or italics <i> for book titles and words as words; use strong <strong> or bold <b> for headings.
    3. Use ordered lists <ol> for step by step instructions.
    4. Enclose HTML code samples within <code> tags.
    5. Enclose PHP code samples within <?php and ?> tags.
11. Linking
12. 1. Avoid title tags unless the text in the link is not descriptive enough. See Dive Into Accessibility - Adding titles to links for more explanation.
    2. Use relative links where possible:
       Bad:
       <a href="http://www.drupal.org/node/1234567">
       Good:
       <a href="/node/1234567">
    3. Links should be embedded within normal descriptive body text:
       Bad:
       I like cat stomachs. To learn more about them <a href="http://www.catstomachsrule.com">click here</a>
       Good:
       My favorite organ in a cat is the <a href="http://www.catstomachsrule.com" title="Information about Cats and their Stomachs">stomach</a>
    4. Use 'www.example.com' as the domain name when describing an example URL.
    5. Link to relevant documentation and forum posts as much as possible. You only need to link to each relevant item once.

Incorporating comments

Incorporating comments made on documentation handbook pages is one way documentation maintainers can usefully edit pages. Although documentation maintainers can not edit or delete the comments themselves, they can incorporate them into the page. An issue report can then be submitted, and a documentation team member who is also a site maintainer can easily remove the incorporated comments. This is also called "rolling comments into the handbook," similar to rolling code patches.

1. View list of pages with comments at http://drupal.org/handbook/comments, which should also appear as a link in the right-pane navigation block "Contributor Links" under "Handbook tools" bullet.
2. Pick a page: Start at the bottom for those with only 2 comments, or start at the top for those with many comments. Or, pick a page that covers a topic which you feel particularly capable of editing.
3. Review: Read the page, read the comments, and determine if there are useful corrections or additional information in the comments. Some pages, such as older Summer-of-code pages, have a long string of comments used for discussion, and their incorporation is not intended.
4. Roll it: Edit the page for corrections and additional useful information that would be good to have in the page. Create a new page (often a child page) if there is new information that is separate from the page's principle topic or focus. The log note should credit the person who provided the information, such as "from comment by username." If the comment is clearly a bug report, convert the comment into an issue and file it under its appropriate project.
5. Create an issue: Use the Documentation project, Task category, and Active status. The title can be as simple as "Delete comments." Put a link to the page in the body. You may group many pages on one issue. If only certain comments were incorporated, then be explicit providing those incorporated, or by exception (those not incorporated). You can specify which comments by URL of the comment or title of the comment.

Joining the documentation team

The Drupal documentation team collaboratively maintains or coordinates:

• the handbooks
• the embedded admin/help text within the Drupal modules
• marketing materials
• other document efforts relevant to the Drupal community

Drupal documentation relies on volunteer effort. The current documentation team coordinator is Steven Peck.

To regularly add pages, edit pages, or help in the handbook organization, join the documentation team. Even new members can significantly contribute to the community by suggesting and making improvements to the documentation as they go through processes for the first time.

Steps to join:

• Subscribe to the documentation mailing list, or at least appreciate that you can follow the exchanges using the documentation archives.
• Submit an issue with category: "support request," and status: "active." Introduce yourself, and request to join the documentation team and be assigned the documentation maintainer role. Mention your user ID number (not the username).

Quick start guide:

• Please familiarize yourself with the documentation guidelines.
• Realize that the top-level pages for modules, both core and contributed, are special; see Embedded documentation.
• Read Major handbook sections for a general overview of the handbooks and their structure.
• Feel free to ask questions on the mailing list or in an issue report if you're unsure in making updates to the handbook.

What to work on and be aware of:

• Any section that you're actually using on your web site!
• Forum discussions which indicate an update is needed and topics which should be incorporated into documentation. Add a reply in the forum pointing the updated or new documentation handbook page.
• Handbook comments is a list of pages by number of comments. These comments should be incorporated back into the main text, or made into sub-pages, as appropriate.
• Most popular pages should be given some extra care to make sure they are clear and easy to understand.
• Handbook updates is a list of recent changes to the handbook. Scanning this list often will help you keep tabs on what's new, and also help remove any spam.

Screenshots and uploading images

Screenshots on Drupal.org must follow these standards:

Format: PNG-8
PNG is preferred because of its lossless compression and small file size. JPEG is not suitable - it leaves artifacts and its 24-bit color depth is unneccesary when dealing with screenshots. GIF is not used because it is an outdated format.

Size:
700 x 700 pixels is the maximum preferred image size.

Browser window:
All screenshots must include the entire browser window; e.g.: the title bar and scrollbars. Capture only the browser window, not the entire desktop; crop the image in an image utility manually if your operating system or capturing utility can't be set to just the browser window.

Remove all distracting items from your browser application including sidebars, tabs, toolbars, Google bars, custom links, etc. Keep only the URL address bar, and make sure it is long enough that the current URL won't be hidden.

Windows XP:
Turn off ClearType font smoothing when taking screenshots under XP, if you can, please. Most people don't have this feature and it increases the file size somewhat.

Uploading:
Attach the image to an issue; that is, submit an issue (with Category "task") for the page you're updating and attach the image you wish to use. Then reference the URL in the page. At present, this appears to be the best method for regular handbook maintainers.

References:
Screenshots in the GNOME Documentation.

Updating API documentation

This document covers updating the API documentation at http://api.drupal.org/.

Code

All documentation for core functions, constants, and files are automatically generated from the core modules in Drupal. For example:

• http://api.drupal.org/api/5/constant/DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE
• http://api.drupal.org/api/5/function/node_load
• http://api.drupal.org/api/5/file/modules/book/book.module

To update these, you must submit a core patch to edit the Doxygen comments of the code in question.

Hooks and other references

In addition to core code documentation, there are also manually created and maintained reference documents for things such as hook definitions, Form API documentation, and example module code. For example:

• http://api.drupal.org/api/5/function/hook_install
• http://api.drupal.org/api/5/file/developer/topics/forms_api_reference.ht...
• http://api.drupal.org/api/5/file/developer/examples/filter_example.modul...

You can also review these files online with viewcvs.

Reporting an error

Anyone with a CVS account can edit these additional reference documents. For minor edits, such as fixing typos or blatant errors, feel free to commit changes directly.

For bigger changes, or if you do not have a CVS account, create a Documentation issue select the Documentation in CVS component. It is important to always create an issue, attached a patch, and include a reference to the issue in the commit message when making significant changes so that other developers can understand what was done and why. In other words, follow the same practives you would follow for committing code to CVS.

Fixing an error

To modify the CVS documentation directly, use the following steps. You can refer to the CVS section of the handbook for more information about using CVS. It is important to remember to make your changes in each version of the documentation that needs it!

1. From the command line, perform a cvs checkout using your CVS account's username in place of "username" below. This will checkout a copy of the HEAD documentation:
   
       cvs -z6 -d:pserver:username@cvs.drupal.org:/cvs/drupal-contrib checkout -d docs contributions/docs/developer
   
   
   To checkout the other versions you need to edit you simply modify the command with the version and make sure you place it in a different local directory, for example:
   
       cvs -z6 -d:pserver:username@cvs.drupal.org:/cvs/drupal-contrib checkout -d docs5 -r DRUPAL-5 contributions/docs/developer
   
   
   You would replace DRUPAL-5 with DRUPAL-4-7 for 4.7.
2. Enter your CVS password when prompted
3. You will need to locate the document you need to edit:
   • The Form API quickstart (forms_api.html) and reference table (forms_api_reference.html) are in the "topics" folder.
   • The hooks documentation is in the "hooks" folder. The particular file will depend upon the hook. If you look at the API page for a hook you will see the source document listed at the top under Description (e.g. developer/hooks/core.php, line 507)
   • Any example code that has _example in the name is located in the "examples" folder.
4. Once you have saved your changes, commit them:
   
   cvs commit -m "Put a meaningful message about what you did here. Also refer to an issue number with a # symbol if one exists (e.g. #112233) and give credit to users who may have provided a patch."
   

Documentation project proposals and specs

Anyone seeking to initiate new documentation projects --project teams and individuals--must submit a project proposal and post and maintain a project spec.

Goals of project proposals

• Allow the documentation community to provide feedback to improve the project.
• Will help to build consensus for projects as part of a vetting process.
• Can help to gain volunteers for the project.
• Makes the project more transparent/open for the rest of the Drupal community.
• Is necessary to gain approval for the project.

Goals of project specs

• Helps to clearly define objectives and guidelines for project participants.
• Allows others, less involved in the project planning, to more easily assist in the project.
• Can serve as resource for developing future, similar projects.
• Makes the project more transparent/open for the rest of the Drupal community.
• Is necessary to gain approval for the project.

Project proposals and specs should attempt to address each of the following:

• Objectives/goals of the project
• Intended audience of documentation
• Relevant issues, i.e.
  • those addressed by the project
  • those that will not addressed by the project
  • any still needing to be addressed by the project
• Timeline or deadlines (if applicable)
• Workflow description
• Guidelines and examples for documentation construction (if applicable)
• List of main participants and/or organizers
• Requests for specific feedback and/or additional project participants (if applicable)

Submitting and maintaining the project proposal and spec:

• The proposal will be posted as a new issue to the Documentation project.
• Feedback from community members should be submitted by posting to the specific project issue.
• Proposal submitters will revise the proposal based on community feedback into a project spec.
• During the project, the project spec should be maintained as changes occur in the project (i.e., new documentation construction guidelines, changes in deadlines, etc.).
• For project teams, active project specs will either reside as a sub-page of the Drupal documentation project teams page for the (for larger ongoing projects) or provide a link to the project from the main project team page.

Documentation writer's guide

This Documentation writer's guide covers overall considerations for the handbook which should be kept in mind when editing and adding handbook pages. This includes topics such as hierarchical organization, editing existing vs. adding new pages, separation of documentation for different Drupal versions, page length, author block, and page weight.

The purpose of these guidelines is to make the handbooks more consistent and usable, particularly the navigation. These guidelines, though written mainly for documentation maintainers, will also be useful for all documentation contributors, who submit issues and can add pages.

In contrast, the style guide offers guidelines for individual page structure, formatting, and markup, as well as language usage, such as italicizing, bolding, spelling, and capitalization.

See Handbooks overview for a description of the five handbooks: "About Drupal," "Installation and configuration," "Customizing and theming," "Developing for Drupal," and "About Drupal documentation."

See the End user guide for help with adding pages or editing pages. All drupal.org users can now create new pages in the handbooks. But when some else updates a page you created, Drupal tracks that person as the page's author, and you lose ability to edit it. To update it, submit an issue, or request to join the documentation team, which will give you permission to edit most handbook pages.

Hierarchical organization:

• Avoid unnecessary layers; they make documentation hard to find and hard to follow. Consider for example how in a book, the appendices are on the same level as "chapters" of the book.
• Do not use hierarchical structure to achieve the desired sequence. Since handbook maintainers do not have access to the weight function, submit an issue; this is a straightforward operation that will generally be performed promptly.
• Avoid nearly-empty "container" pages.
• Introductory material should normally be in the parent page, not a first child page, in a large multi-page topic.
• Short child pages covering a particular variation should be incorporated into the parent page if practical. This is particularly true for single child pages.
• Avoid duplication; it is better to link to existing documentation about a topic, rather than duplicate it (or nearly duplicate it) in a second location where it may be applicable.
• Ensure the parent page is organizationally named. Remember that a user starting at the top sees only one layer of titles at a time. Would someone looking for the topic on your page naturally select its parent from those available? If not, submit an issue report against the parent page's title.
• Test the structure: Start at the top, and select the path a new user would if looking for your topic. If there is an absence of a clear path, or multiple plausible paths, submit an issue.
• Consider forum requests: If the documentation page exists, but a forum inquiry indicates it couldn't be found, consider whether the documentation handbook structure is unclear for a new user looking for the topic. Rather than just providing a link to the page, provide the path to the page as well.
• Hierarchy example:
  
  Bad:
  
  Main topic
--Theory
--Implementation
--Examples
----Example one
----Example two
--Special circumstances
----Case one
----Case two
  
  
  Good:
  
  Main topic
--Theory
--Implementation
--Example one
--Example two
--Special circumstance considerations
--Circumstance one
--Circumstance two

In this example, the "Special circumstances" page in the top structure covered general considerations and was more than an organizational place holder, so a "Special circumstance considerations" page was placed ahead of the special circumstance cases in the bottom structure.

Titles: In addition to the Style guide directions, also consider how the title of a page fits in to the overall structure. Is there a long flat list of titles, many of which "almost, but not quite" match a user's question?

Main chapters: The five handbooks should generally each have twelve chapters or fewer, since the "Handbooks" tab shows all the top-level chapters of all of the books.

Editing versus adding pages: Try to edit current pages rather than create new pages. It is better to cover a topic in one location succinctly, and then reference the topic from related pages. Editing existing pages rather than creating new ones also preserves links that reference current pages.

Versions: There is only one set of documentation handbooks, since many pages apply to all versions of Drupal; since there are insufficient resources to maintain different sets of handbooks for different versions of Drupal; since inconsistencies would develop between parallel versions due to only one book being corrected when the problem affects both; and since guidance on the only available version is often useful to the reader who has a different version.
      Information for different Drupal versions can be kept together on one page or separated on different pages. It is generally preferred to cover information for all the versions on a single page, but if instructions for the different Drupal versions differ substantially, separate pages are appropriate. Use the "Drupal version" drop-down menu and select which version(s) the page applies to.

If each version is dealt with on a separate page:

• Organize the pages on the same hierarchical level.
• Include the version number at the end of the title, so that one page is titled "Example topic, v. 5.x" and the next is "Example topic, v. 4.7."

If multiple versions are dealt with on one page:

• Select all the versions which the page applies to in the "Drupal version" drop-down menu.
• Information on the page should be listed from newest to oldest version.
• Mark the sub-sections for each version very clearly.
• If there are no separate subsections for the different versions because the entire page applies to all versions selected in the "Drupal version" drop-down menu, state so early in the page, so that readers don't wonder which sub-sections apply to their version.

Page length: Longer pages of several screens are acceptable. Use <b> or <strong> tags to provide sub-topic headings within the page. Very long pages should list the page contents (preferably with links) after the opening paragraph.

Authorship: Avoid changing page authorship unless you have done a major re-write. (Currently, only site maintainers have access to the author field.)

Log message: Enter a brief log message to explain the page update.

Weight: Only site administrators can change the order of pages that appear under a common heading. To request such changes, submit an issue report.