Advertising sustains the DA. Ads are hidden for members. Join today

On this page

2.5. Style Guide for the Editing Phase

Last updated on
11 January 2024

The sections below contain a style guide to be used during the copy editing phase.

The guidelines here are partially based on:

Also note that these guidelines are for the text that will appear in the book’s output. They do not apply to:

  • Comments (lines starting with //)
  • Code (PHP, JavaScript, etc. included in the text)
  • Commands (examples of what to type at the command line)

2.5.1. Guidelines appropriate for single-task issues

The following style guidelines can be applied by volunteers, where each volunteer would undertake the task of applying one guideline (independent of the others, and across the entire User Guide):

  • Make sure that the Goal section in task topics is expressed as a specific goal for the site, not as the learning goal or something generic. For instance it should be "Add a content type for vendors to the site" not "Learn how to add a content type to the site" or "Add a content type". Also it should not start with "The goal …", but should start with a verb.
  • Make sure that the Site prerequisites section in task topics is expressed as what you need to have on your site, not as steps or tasks. So for instance, it should say that a certain module must be installed, or that a content type must exist, rather than saying "Install a given module". Also it should link to topics that tell how to achieve the prerequisite.
  • When providing instructions for interacting with the user interface, use the following styles. For clicking on a link or button, use the phrase "Click (link or button text)", rather than "click on", "select", or other terms. For a select list or radio button, say "Select (choice)". For a checkbox, say "Check (choice)". For a drop-down list of operations links, say "Click (choice)". Make sure that the actual UI text you are selecting or clicking on is in italics.
  • The gear wheel icon you click on to open field settings should be referred to like this: "Click the gear wheel for the _ field".
  • There are two types of dropdown user interface elements. When referring to select lists (lists of choices in an HTML "select" tag, such as what you would see when you select a language to add or the default country), use the term "select list". When referring to buttons that contain lists of links, such as what you would see in an Operations section of the Content form at admin/content, use the term "dropdown button" (not drop-down or drop down).
  • There are several types of details-type user interface elements (elements that can collapse or expand to hide or show sections of the user interface). These include fieldsets and vertical tabs, and most of them have titles that you click on to show/hide their content. When referring to these types of user interface elements in text, use the phrase "under (title)", and always provide this information to help people locate the correct area of the user interface. When referring to fields inside such elements in tables of fields, explanations, and values, use notation like "(title) > (field)".
  • If a step in a task includes a screenshot, it should go after the description of how to do the step. If there is also a table of values for filling out the form, the screenshot should go after the table of values. Screenshots should always have alternate text, but should not have captions. The alternate text should NOT start with "screenshot" or "screen capture" or "image". It should describe what is in the image.
  • Referring to a module, installation profile, or theme — use a style like: "the core Contextual Links module", "the core Bartik theme", "the core Standard installation profile", or "the contributed Admin Toolbar module". No italics. Also, capitalize the module name (like "the core Views module") but not the "things" it works with (like "you can create views of your data").
  • Links for contributed modules and themes — All mentions of contributed modules and themes should link to the Drupal.org page for the module or theme project. Make the link text be, for example, "contributed Admin Toolbar module" or "contributed Bootstrap theme".
  • Index entries should be singular ("block" not "blocks"), and have duplication and synonyms consolidated into one entry. They shouldn’t have any quote marks when they’re listed in the output.
  • Links to topics (internal links) should generally have link text equal to the topic title. The link text can be overridden in a paragraph as long as the link text still makes it clear that the link is going to a topic, but it is preferable to say something like "See __ [leaving topic name as the link] for more information".

  • When making a link to an outside URL, make sure the link text tells the reader what web site it is going to:

    • Link text to use when linking to one page within a larger site — examples:

      • Wikipedia page "Cross-Site Scripting"
      • Drupal.org community documentation page "Installing Drupal"
      • Blog post "All About Views"
      • YouTube video "Setting up a View"

    • Link text to use when linking to an entire web site or major site section — examples:

      • groups.drupal.org, api.drupal.org, Drupal.org [the site URL without the https etc.]
      • Wikipedia, Twitter, Facebook, JQuery Documentation, Drupal.org Community Documentation [the name of the site or large section within a site]
  • Avoid using the word "Drupal", except when referring specifically to the Drupal open-source project, the Drupal community, or the Drupal.org web site. Instead, refer to "your site" and "the core software".
  • Avoid mentioning specific Drupal versions, such as Drupal 7 or 8.
  • Avoid the words please, congratulations, be sure to, just, simply, or thank you (and similar words). Instead, tell the reader what they need to do.
  • Avoid using "we" and "I".
  • Avoid using e.g. and i.e.. The reason is that these are often confused for each other by both writers and readers. Instead, write out "for example" or "for instance", and "that is".
  • Upgrade vs. Update: In the context of software versions, upgrade means changing the software version from one major version of Drupal to another, and adapting the site, database, and code to this new version. Update is anything less than that, such as moving to a new version of a particular module or a new minor core software version. (Note that the word update can also be used in other contexts, such as updating content or configuration. This standard only applies to its use in the context of changing the version of software.)
  • email vs. e-mail: use email
  • entity terminology: use the terms "entity type", "entity subtype" (not "sub-type" or "bundle"), and "entity" (not "entity item").
  • website vs. web site: use website

  • enable vs. add vs. install vs. upload vs. place:

    • For themes/modules, use the words "installed/uninstalled" to mean turning them on/off (not enable/disable or add/remove or turn on/off).
    • For updates to themes/modules/core, use the phrases "apply the update", "update the site", or "update the software" (not install or make).
    • When talking about putting files for modules, themes, or updates onto the web server, use the words "upload" or "copy" (not install, add, or place).
    • For languages, use the word "add" to mean turning them on (not enable).
    • For blocks, use the word "place" to mean putting them in a theme region (not enable, add, or install).
  • directory vs. folder: use directory.
  • contrib vs. contributed: Refer to contributed modules and themes as "contributed", not "contrib". However, they can be placed in a directory called "contrib" in your modules/themes folder.
  • File names, URLs, URL paths, and directories should be in italics. For URLs within the reader’s site, if providing a full URL, use base URL example.com. See Section 1.2.8, “Typography formatting” for formatting instructions.
  • Commands typed at a command prompt should be in monospace. See Section 1.2.8, “Typography formatting” for formatting instructions.
  • Every list should be preceded by either a header or a colon ( : ). List items that are sentences end in period ( . ); list items that are not sentences do not end in period ( . ). Lists with only one item should be turned into regular paragraphs.
  • Use double-quotes, except for quotes-within-quotes.

2.5.2. Guidelines not appropriate for single-task issues

The following guidelines should be applied by having a person or people edit each topic so that it follows all of the guidelines:

  • Generally, use standard American English (with standard American English usage, spelling, and punctuation). For standard usage, see The Elements of Style (Strunk and White) and/or The Chicago Manual of Style. If you use a spellchecker, make sure that it is set to American English (en-us).
  • Write in second person, active voice, and imperative mood as much as possible (aside from Site Prerequisites, which are passive voice). Examples: Click the Add new content link, your site.
  • Use the serial comma for lists inside sentences. Example: apples, oranges, and pears.
  • When writing about things you can see in the Drupal user interface: use the exact words that someone would see in the UI, with their exact capitalization, and put the UI words in italic typeface. See Section 1.2.8, “Typography formatting” for formatting instructions.
  • When writing about text the user has entered, such as names of content types and fields, do not use italics. This applies even if when you are writing about the item, you are describing what appears on a screen. Example: when adding a field to a content type created earlier, don’t put the name of the content type in italics, even though it appears in the UI screen at that point.
  • Follow the guidelines in Section 2.2, “Writing Good Documentation”.
  • Follow the guidelines in Section 2.3, “Following the Scenario” (mainly for task topics) and Section 2.4, “Style Guide for the Writing Phase”; these should have been enforced during the writing phase.
  • When introducing new terminology for the first time, put the term in italic typeface, and define it in parentheses or in a regular sentence. Also make sure the terms are in the glossary topic.

Attributions

Written/edited by Jennifer Hodgdon and Joe Shindelar.

 

This page is generated from AsciiDoc source from the User Guide. To propose a change, edit the source and attach the file to a new issue in the User Guide project.

Source file: guidelines-editing.asciidoc

Help improve this page

Page status: No known problems

You can: