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
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 tutorials.
4. Avoid numbering child pages; use page weight to properly order them. Use "1." style numbering if you must, not "1)" or "1-"
2. Writing style
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.
3. Spelling and capitalization
1. Use US English spelling. For example, color, not colour.
2. Drupal, not drupal
3. email, not e-mail
4. HTML, not html
5. URL, not url
6. PHP, not php
7. MySQL
8. JavaScript, not Javascript
9. HowTo:, not HOWTO:
4. Paths
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.
5. HTML and code formatting
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.
6. Linking
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.