Handbook style

The Drupal Editorial Style Guide maps out the style and voice to provide consistency and best practices, and to reinforce the Drupal brand. Use it:

• On main landing pages and other editorial sections of the site
• To describe modules, themes, features
• To guide writing when contributing to any page on the site or wherever Drupal speaks: ads, event literature, etc.

The Style Guide also provides suggestions for communication in forums and groups.

Every Drupal user has many opportunities, big or small, to contribute to the site in important ways, as it evolves. In fact, your page may be the first one a visitor sees, and will set the tone for his or her experience of Drupal. The Editorial Style Guide helps us speak with one voice—the Drupal voice—even as we remain strong individuals.

Style guides can be hundreds of pages long. The Drupal Editorial Style Guide covers highlights.

Contents

• Recommended Resources
• Voice
• British/American Differences
• Capitalization of Titles and Headings
• Writing Style
• Punctuation
• Paths and Navigation
• Links
• HTML and Code Formatting
• Numbering, Hyphens, Dates
• Industry-Related Words
• Naming
• Acronyms and Abbreviations
• Drupal-Specific Terms
• Miscellaneous Notes on Usage
• Person-to-Person Communication
• Including New Users and Visitors
• Explaining Version Differences

Recommended Resources

• Elements of Style by Strunk and White (Drupal guide overrides any differences between it and choices in Elements of Style)
• Oxford American Dictionary
• The American Heritage Dictionary
• The Chicago Manual of Style (Our ultimate reference, but too expensive for average user.)
• The Economist Style Guide (Wonderful book but much information is British-based. Contains excellent section on British/American differences.)
• wikipedia.org has a quick summary of the main differences between American and British English.

_{Back to Top}

Voice

Reinforce the Drupal brand: Scan the beginning of the Drupal Brand Style Guide before writing. Anything written at Drupal.org becomes part of the Drupal experience and should convey the Drupal spirit.

• Be clear, simple, concise, engaging, welcoming, lively, honest, fun where appropriate, respectful, and approachable.

New to themes? Here's [link text: how to get started]. Only cut-and-paste PHP knowledge needed. Questions? Find people happy to [link text: help in the forums] or [link text: hire a developer].

You should already know about themes in general. If you want to find out more, read that section because it will give you all the details you need. You will need to know some PHP but not much. If you aren't an experienced developer, I don't think this section will help you very much and you probably should hire someone to do it for you.

• Use ordinary, everyday language instead of words that sound more elevated--they usually don't.

Use this to...

Leverage this to...

Utilize this to...

Know your audience: Tone of voice, use of jargon or Drupal nicknames, and complexity of language should be appropriate for the type of page:

• Major landing pages must be approachable and appropriate for a wide audience that could include beginners, company managers, designers, developers, business owners, first-time bloggers, tech-savvy entrepreneurs, educational organizations, advanced Drupal developers. Keep them in mind.
• Deep-level pages (e.g., discussing the complexities of module-building) while still using the Drupal tone of voice, can be more complex and use jargon and "insider" names for Drupal functions and features.
• Use empathy: Put yourself in the place of the readers. Try to look at your text through the eyes of a variety of visitors.

Get them there: Ask yourself what visitors want to get done and help them get there quickly.

Short isn't always best: Concise (brief yet comprehensive) is good, but shortness? It depends. What does the user expect and need?

• If you are just trying to attract attention, do that, with a short, snappy headline. Snappiness, though, is not always necessary. To persuade someone or show Drupal personality to a new visitor, use attractive, compelling words. To simply get someone to the proper destination, link text "See Documentation" is fine, and so is the heading "Documentation."
• If the user needs or is looking for a lot of information at this point, provide it. Don't be afraid to go into detail, no matter what advice you've read. With proper headings, whitespace, subheads, padding, links, short paragraphs, charts, and lists, length here is a good thing. Unnecessary words? Not good.

Open source not market-speak: Avoid fluffy sales talk. "We're great! Drupal is great!" "We're the best!" These sentences are only believed by those who write them, not those who read them.

• Words such as "very, really, truly" tend to weaken a statement, not strengthen it.

This module reduces the time you need to set up a forum.

The module really reduces the time you need to set up a forum.

EVEN BETTER: This module shortens forum set-up time.

Edit and edit again: Strip away unnecessary words. Examine them. Is each one lively, direct, and doing a job? Or, is it empty or deadening? Because an informal voice is brand-consistent, complete sentences aren't always necessary:

"Can't find the answer?"

"Are you having trouble finding the answer to your question?"

PHP expertise necessary? Yes.

PHP expertise is necessary.

Expertise in the use of PHP is very necessary for using this module.

Think globally: Avoid phrases that aren't easily translated, such as puns and social or local references. Beware of wit or cleverness that won't have the same meaning in other countries. Light humor, in good taste, is good, but will it translate?

(PDF 514 MB)

(PDF 514 MB) Better get out the popcorn and watch The Big Lebowski while you're waiting for this bloody thing to download.

Be clear about benefits for the reader: Drupal is here to make people awesome at what they do. Using the word "you" can be powerful.

In general, use active, not passive, voice: In active voice, the subject performs the action. In passive voice, the subject is the target of the action. Don't twist sentences into knots trying to avoid this, though. Also, at times, passive voice emphasizes words that active voice would downplay; if so, use passive voice, but, in general, use it sparingly.

You should clearly identify links.


Clearly identify links. ("You should" is implied.)


Links should be clearly identified. (Here, the links aren't doing something; someone is doing something to them)

Click the download button to get the core files.

The download button should be clicked in order to obtain core files.

Quick Resource: http://owl.english.purdue.edu/handouts/grammar/g_actpass.html


Resource for variations in non-English languages: see "active voice" at wikipedia.org.

Avoid first-person: Avoid first-person (I, we, my, our) on editorial/landing pages. Use "Drupal" instead. At times, because Drupal is community-based, use "we" to sound inclusive or to reinforce the community concept. Avoid first-person in sections such as Documentation or Modules, etc.

This module helps you add feature x.

I created this module to help you add feature x.


Drupal releases a new version every six months.


We release a new version every six months.

Things We Made with Drupal (Exception to first person rule, on homepage. ("We" conveys sense of real Drupal people with real stories.)

Avoid a condescending tone in instructions for new users: Use clear, descriptive text in links to additional or clarifying information. At the same time, experienced users need quick steps. Find the balance. You don't need the word "Please" in order to sound friendly. At times, it will be appropriate; usually, it will not.

User-test your writing: Choose at least one person from your intended audience to make sure directions are clear and complete, and the tone is correct. User-testing is critical for sections like Modules and Documentation. If it is written for a new user with basic skills, you should test it on new users with basic skills. They should be able to achieve the instructions's final goal without asking you any questions.

Humanize buttons: "Submit" and "Click Here" are not as clear or personable as "Sign me up," "Join now," "Please enroll me," etc.

_{Back to Top}

British/American Differences

Drupal uses American English rules for spelling and punctuation.

Spelling examples:

• Color, not colour
• Organize, not organise
• Gray, not grey
• Spelled, not spelt
• While, not whilst
• Center, not centre
• Meter, not metre

Treat companies and organizations, although made of groups of people, as single entities:

Microsoft has many products.

Microsoft have many products.

Harvard University has decided to close for the summer.

Harvard University have decided to close for the summer.

The Drupal community needs more money.

The Drupal community need more money.

Punctuation examples:

• Use a serial comma: A comma follows the last item in a list, before the and. The exception is when two associated items that form a name or pair are on the list. These are not separated by a comma.

I like writing, reading, spaghetti and meatballs, bicycling, and receiving Christmas presents.

I like web designs by Happy Cog, Clearleft, Veerle and Geert at Duoh!, Airbag, and Mark Boulton Design.

I like apples, pears and pineapples.

• Don't use the serial comma in headings and titles.

When a colon precedes a full sentence or question, the first letter after the colon should be a capital letter.

Consider this: Men are different from women.

Consider this: men are different from women.

She wants many things for Christmas: boots, lingerie, shoes, perfume, and jewelry.

Quotation marks:

• Single quotes are used only when a quote appears within a quote.

Mary said, "I don't know why she said 'No,' when I asked her."

Mary said, 'I love to attend Drupalcon.'

• Final quotation marks in a sentence or phrase are used after the period or comma, even when naming something.

Add features to the Drupal core by using things called "modules."

• Put quotation marks before semicolons, and colons.

Em dashes shouldn't have a space on either side.

Capitalization of Titles and Headings

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.

All main headings, subheadings, the name Drupal, and the titles of books and magazines use initial caps.

Things We Made with Drupal

Downloading Drupal

• Exception: The title for individual features on the About Drupal page are all uppercase.
• Exception: Titles of news articles, forum titles use sentence case, in which the first letter of the first word is uppercase and all other words are lowercase, other than Drupal, titles and names.

CCK 2.0 for Drupal 6 officially released

Announcing O'Reilly Drupal book: Using Drupal

Everyone can edit handbook pages

• Exception: Brief instructions that aren't headings should be sentence case. If in doubt, use Initial Caps.

Refine your search

Request new password

• In headings, use initial caps for the first letter of major words, and the first letter of the first word in the heading. Don't capitalize a, an, the, and, but, or, nor, for, yet, so, as.

Don't capitalize prepositions that are less than five letters: at, by, for, from, in, into, of, off, on, onto, out, over, to, up, and with. The exception for prepositions is when the word is part of a verb phrase.

Do capitalize are, if, is, than, that, and this.

Log In to Join This Group ("In" is part of the verb phrase Log in.)

Learn More in the Module section.

• Use initial caps for both words in hyphenated compounds, such as First-Rate Methods.

Put initial words in bold in sentences that begin with a description of the item in a list or otherwise clarify the contents of a paragraph. Use the <strong> element for bolding words. Only use <em> if a particular word needs to be emphasized for a specific reason.

Even better: Make those initial words into a heading. See for yourself which looks better. If many headings break up a page too much, include the bolded words in the beginning of each sentence or item. If headings bring clarity to a page, use them instead.

See the administration section: to learn how to configure and manage your site and use modules, blocks, permissions, and themes.

Administer Your Site

Learn how to configure and manage your site and use modules, blocks, permissions, and themes.

Use "HowTo: {title}" for documentation pages that function as step-by-step recipe-type tutorials.

Avoid numbering child pages; page weights can properly order them, but this requires site maintainer rights. If you need pages reordered, make an issue stating which pages and the order you want them. If you do use numbering (e.g. temporarily) use "1." style numbering, not "1)" or "1-"

A heading should never be followed by another heading. For example, you should never start a page with a heading (other than what is in the page's Title field).

Do not use bold <bold> to mark headings. <em> and <bold> tags do not have any semantic sense other than for emphasis.

Never use the <h1> tag for headings. This tag is added automatically to the page title. If a page has major sections use <h2> instead and use <h3> for the subsections. Use of <h4> etc. should not be necessary. Never use heading tags for emphasis. These rules are important for enabling accessibility.

Never end a heading or page title with a period (.), colon (:), semi-colon (;) etc.

_{Back to Top}

Writing Style

• Keep sentences to 15 words or less. Long sentences are difficult to understand.
• Avoid using first-person pronouns: I, my, we, our, etc.
• Resist the overuse of you, your, one and one's. The Fedora Project StyleGuide has good suggestions regarding pronouns.
• Use a single space after a period.
• Spell check.
• Don't be wordy or colloquial. This benefits all readers, but especially Drupal users with a first language other than English.
• Do not assume that the reader will be familiar with cultural references.
• Use inclusive language wherever possible. For example, "You will see a block at the top of the page ..." assumes that the reader can see. It's better to write "A block is displayed at the top of the page ...". .

_{Back to Top}

Punctuation

Use curly (smart) quotes unless you are providing code examples.

Use only one space after a period.

Don't use the ampersand in text. Use it only in code examples or when referring to a page title that uses an ampersand (Community & Support)

• Ampersands should only be used in titles in the main navigation buttons and in the title of each corresponding page.

Community & Support is a legitimate title because it is in the main navigation. The title of that landing page should also be Community & Support.

Drupal's Most Popular Modules and Themes

Drupal's Most Popular Modules & Themes

If a phrase in parentheses is within a sentence, put the period at the end of the sentence, not within the parentheses. If the phrase in parentheses isn't within a sentence, place the period within the parentheses.

(We are new here and didn't know what we were doing.)

I don't know why we did that (I guess we didn't know what we were doing).

Punctuating lists:

• Precede an ordered or bulleted list with a sentence or phrase ending in a colon.

In Groups, you can:

• Get to know other Drupal users
• Collaborate on projects in a small group
• Voice your opinion on a particular project
• Begin each item with a capital letter (unless it is a product or company name that begins with a lowercase letter).
• Complete sentences in a list should have a period at the end; otherwise, do not use a period. If you are breaking a sentence into a list, as in the first example in this section (In Groups), periods aren't necessary.
• Be consistent, if possible, when writing the items in the list. Make them "parallel." In the first example, Get, Collaborate, and Voice are the same form of verb.

• Getting to know other Drupal users
• Projects that need lots of people
• State your opinion

_{Back to Top}

Paths and Navigation

• When describing how to get to a specific user option in the interface (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)

• Do not abbreviate words in the navigation path (e.g., use administer instead of admin).
• Menu items can move. So rather than just describing which menus or links to click, also include the path, using example.com for the web site (ex: path > to > item > destination, or http://example.com/path/to/destination). If you enclose your URL in a <code> tags, you will avoid having it turn into a clickable link.
• If the path in search leads through a sidebar note, include the sidebar heading or link in parentheses after the page's heading.
  Home > Modules (sidebar) > Popular Modules >

_{Back to Top}

Links

• When embedding a link in a Handbook page, always make sure the link text concisely describes the destination of the link, and meshes with the rest of the paragraph. You can also add a "title" attribute to a link, if the link text is not able to fully describe the destination of the link and still maintain good sentence flow. Title tags, used appropriately, are important for making the handbooks accessible.

Examples of link text:

Learn how to organize a Drupal event

how to organize a Drupal event (this is the best one, given the subject)


organize a Drupal event

Drupal event

event

The best place to learn how to organize a Drupal event is on the Drupalcon homepage.

Always warn users if clicking on a link will lead to a PDF or other download, including modules, etc. They may think they are clicking on something that merely provides more information, rather than immediately downloading a file.

Ex. [link text: Learn how to organize a Drupal event]. (PDF 3MB)

Do not include punctuation at the end of link text in the link itself. See example above.

• Use relative links where possible:
  Bad:
  <a href="http://www.drupal.org/node/1234567">
  Good:
  <a href="/node/1234567">
• Embed links 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>
• Use 'www.example.com' as the domain name when describing an example URL, and embed the "link" in <code> to avoid it turning into a clickable links.
• Do not use target= attributes on links to make them open in a new window or tab. This is no longer considered to be good practice on the web in general.
• Link to relevant documentation and forum posts where ever it would be helpful. Provide a link to any specific item, only on its first occurrence in a page.
• Glossary links:

  Link to a specific Drupal term:
  

  <a title="see Taxonomy" href="http://drupal.org/node/937#t">Taxonomy</a>

  Link to a common expression used on Drupal.org:
  

  <a title="Find under A - List" href="http://drupal.org/node/302232#a">AFAIK </a>

_{Back to Top}

HTML and Code Formatting

• Avoid the underline tag <u>; use emphasis <em> instead. The <em> tag is also used for italics and book titles.
• Use ordered lists <ol> for step-by-step instructions and for lists of items that have an order of priority. All other lists should be "unordered", however it is often helpful to the reader if a list is still sorted in a way that is appropriate for the context (alphabetical, earlier to later etc.)
• Enclose HTML code samples within <code> tags.
• Enclose PHP code samples within <?php and ?> tags.

_{Back to Top}

Numbering, Hyphens, Dates

Provide a key or footnote on every page that uses a symbol, even a symbol that seem obvious to you. For example, the symbols used on the Modules page (e.g., checkmarks) should be explained in a short footnote.

Only number list items if they are a set of instructions or, perhaps, a list of reasons (Ten Most Popular Drupalcons, or Here are ten reasons to use this method). Generally, lists should be unordered (not use numbers).

Use em dashes (HTML entity 8212), for abrupt breaks in a sentence, to temporarily change subject within a sentence, for clarity, to draw attention to a point, or to signify the origin or author of a quotation.

• Don't use double hyphens; use the HTML entity.
• Don't place spaces on either side. There shouldn't be any space between the word or words next to an em dash and the em dash.

Use an en dash (HTML entity 8211) to indicate a range of numbers or dates. (See www.alistapart.com/stories/emen/ for more information about the subject of dashes and hyphens.)

Express dates either in full (December 6, 2008) or use the proper ISO order: yyyy-mm-dd, as in 2008-12-06, depending on where it is being used. This may be irritating to users of American English, but is the ISO standard and the standard for software. An American event probably would use the full word version (Drupalcon, December 6-7, 2008) whereas a date for an entry or update might use the ISO version—but keep pages consistent.

_{Back to Top}

Industry-Related Words

Correct:

• e-mail, not email
• e-commerce, not ecommerce
• e-learning, not elearning
• (e-words are always lowercase, except at the beginning of a sentence or in a heading)
• website or site, not web-site or web site
• homepage, not home page
• web page
• web, not Web
• the web, not the Web
• nonprofit
• internet, not Internet
• webmaster
• sidebar
• sub-page
• page view
• blog (not weblog)
• web publishing
• web server
• Drupal, not drupal
• back end, front end, unless describing a noun. Correct: Change the front end. He's a front-end designer.
• server-side, not server side or serverside
• PHP, not php
• URL, not url
• HTML, not html
• XHTML, not xhtml
• MySQL
• JavaScript, not Javascript
• Ajax, not AJAX or ajax
• HowTo:, not HOWTO:
• username, not user name
• online, not on-line
• FAQ stands for Frequently Asked Questions; don't add an "s" to pluralize it
• login (noun): Ex. Use the login section.
• log in (verb): Ex. Log in by entering your username.

Exception:

• When a word is lowercase, such as web, it uses an uppercase first letter when it is the first word in a sentence or heading.

_{Back to Top}

Naming

When naming modules, themes, and other features, avoid jargon and Drupal nicknames as best you can, as well as names with private meanings. It alienates the new user.

Timekeeper
Beastmaster_IQ4
ab.cron_cctime

_{Back to Top}

Acronyms and Abbreviations

Pluralize them by adding an "s" without an apostrophe. Only use the apostrophe if you're describing something possessed by the acronym.

URLs, DVDs

URL's, DVD's
The DVD's surface is scratched.

The first use of an acronym or abbreviation on a page should be spelled out, even in a list. Thereafter, on that page, only the acronym or abbreviation is necessary. This is important in the Forums, as well, because this may be the first entry point for a new user.

Ex: The Content Construction Kit (CCK) allows you to add custom fields to nodes using a web browser. Once you update the core CCK modules and ensure that they are working properly, add other CCK modules to the modules folder.

Exception: You don't need to spell out widely-known acronyms and abbreviations that are even familiar to non-technical visitors.

Examples: RSS, URL, DVD

_{Back to Top}

Drupal-Specific Terms

The first use of a Drupal-specific word on a page should be spelled out, even in a list. Thereafter, on that page, only the jargon, shorthand word, or nickname is necessary. This is important in the Forums, as well, because this may be the first entry point for a new user.

Ex. Contrib

Drupal versions: Don't use phrases like "latest version" or "Drupal," as in "Download Drupal." Always call a version by its full name: Drupal 6.3. or Drupal 6.x or even Drupal version 6.3. Don't use "Update" when referring to versions of Drupal.

Download Drupal version 6.3 before using this module.
Download Drupal v. 6.3 now.
With Drupal 6.3, you can do amazing things.

Download Drupal
In the latest version of Drupal, you can do amazing things.

Terminology is not capitalized unless you are referring to a section or page on the site.

Use modules to add features to your site.
Use Modules to add features to your site.

See the Modules page to discover new features for your site.

See the modules page to discover new features for your site.

_{Back to Top}

Miscellaneous Notes on Usage

Generally, when giving examples, use "such as" rather than "like." Use "like" to replace "in the same way that" or "as though."

Drupal.org has many sections, such as Features, Community & Support, Modules, and Documentation.
Drupal.org has many sections, like Features, Community & Support, Modules, and Documentation.

Participate in the forums frequently, like webchick and Dries.

Many people participate frequently in the forums, such as webchick and Dries.

Alt attributes: All images, other than purely decorative ones (such as background colors) should be described using an alt attribute.

_{Back to Top}

Person-to-Person Communication

Brand-consistent communication in forums, groups, and other points of contact is essential for reinforcing the brand and inspiring people to not only use the software but be passionately involved in the Drupal community.

Communication should, of course, be in your own voice. Make a point, though, to review your tone and choice of words before hitting "Send." Is your message off-putting or does it encourage further communication, inspire participation, or include other people in a collaborative manner? Does it meet others halfway?

Even if other people irked you intentionally, did you rise above that and respond in a friendly way, or did you go down to their level? Remember that a forum or group may be the first page that a potential user sees at Drupal. This new person may hurry past any login and only start reading once reaching the forums. Be informative, kind, welcoming, informal, and full of good humor.

See www.alistapart.com/stories/puttingourhotheadstogether/ for ideas on how to use the forums for the betterment of Drupal, its brand, and its users (experienced and new).

Also see the comprehensive "forum tips" section, linked to in the introduction to the Forum.

_{Back to Top}

Including New Users and Visitors

Intros to sections should use a welcoming, friendly tone, as one colleague to another, should specify what sort of things people can do to help Drupal (the site, community, or software), and should pay particular attention to indicating how even those new to Drupal can help.

For example, for new users visiting the Documentation landing page, it is encouraging to see words like these:

"If you are new to Drupal and have trouble understanding any part of the documentation, please [link text: notify those of us who work on this section] and clearly explain what you don't understand and why. We're happy to hear from you. Your contribution helps everyone at Drupal!"

Why say "notify those of us who work on this section" rather than just say "notify us"? It subliminally suggests that a group of people--volunteers rather than a distant or intimidating authority, write these pages.

Text like this has a brand-consistent voice, helps more people use Drupal-- not just download it, and shows new users how they can be important to Drupal. That, in turn, will encourage them to begin the journey to mastering Drupal and telling others about their great experience with Drupal.

_{Back to Top}

Explaining Version Differences

When explaining differences between Drupal versions, there are two options. If a procedure or interface is substantially different between the two versions, consider creating two separate pages and noting the version at the end of the page heading. For example:

• Creating a widget (Drupal 5)
• Creating a widget (Drupal 6)

If there are only minor differences between versions (for example, if a step in a procedure is different), place each chunk of information in a separate paragraph and note the version at the beginning of the paragraph, earlier version first, later version second. For example:

• (Drupal 5) Click X.
• (Drupal 6) Click Y.

_{Back to Top}