[[guidelines-editing]]
=== Style Guide for the Editing Phase

[role="summary"]
Guidelines for editors of the project_name to follow.

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

The guidelines here are partially based on:

* https://www.drupal.org/style-guide/content[Drupal.org Style Guide]
* https://www.drupal.org/node/604342[Drupal.org Interface text conventions page]

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)

[[guidelines-editing-tasks]]
==== 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 project_name):

* 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

* *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
<<style-literals>> for formatting instructions.

* *Commands typed at a command prompt* should be in monospace. See
<<style-literals>> 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.


[[guidelines-editing-overall]]
==== 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 <<style-literals>> 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 <<good-writing>>.

* Follow the guidelines in <<follow-scenario>> (mainly for task topics) and
<<guidelines-writing>>; 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
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] and
https://www.drupal.org/u/eojthebrave[Joe Shindelar].
