[[guidelines-writing]]
=== Style Guide for the Writing Phase

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

The sections below contain guidelines to follow in your text when writing for
this guide. You'll also want to keep in mind the ideas in <<good-writing>>, and
especially if you are writing a task topic, <<follow-scenario>>. If you want to
think ahead, you can also look at <<guidelines-editing>>, but this is not
required.

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]

On this page:

* <<guideline-lists>>
* <<guideline-text-caps>>
* <<text-navigation>>
* <<composing-index-entries>>
* <<guideline-additional-info>>


[[guideline-lists]]
==== Use lists appropriately

Use numbered lists for sequential task steps, and bullet lists for sets of
options, notes, and the like. Only use a list if it has at least two items in
it. See also <<formatting-paragraph>> for the mechanics of putting lists into
your topic.


[[guideline-text-caps]]
==== Reference Drupal components and interface correctly

When referring to a specific module or theme, capitalize it as follows:

* ... the Foo Bar module ...
* ... the Foo Bar theme ...

When referring to text that the user can see in the user interface, use the
_exact_ text that they will see, and put it in italics.

Example:

----
Click _Save configuration_.
----

which is formatted as:

Click _Save configuration_.


[[text-navigation]]
==== Describing navigation

In most task topics, you will need to provide instructions for how to find
pages in the Drupal administrative interface. Here are two examples of how to do
this:

----
In the _Manage_ administrative menu, navigate to
_Structure_ > _Taxonomy_ (_admin/structure/taxonomy_).

In the _Manage_ administrative menu, navigate to
_Configuration_ > _System_ > _Site information_
(_admin/config/system/site-information_).
----

Notes:

* Refer to the administrative menu as the "Manage administrative
menu". (The reason for doing this is that it is sometimes hidden, and to
make it visible, you click on "Manage" in the top bar of the screen,
assuming you have the Drupal core Toolbar module enabled.)

* From there, use the exact link text for the links someone would need to
click; on the Configuration page, also include the name of the
category/section the link is in.

* Each link text or section is in italics (underscores make words italic in
AsciiDoc), because it is user interface text.

* After the complete navigation, include the path to the page, starting
with "admin", in italics because it is a URL path.

* Do NOT include a screen shot of the navigation.


[[composing-index-entries]]
==== Composing index entries

Index entries should usually be two-level entries, such as `Block, creating` or
`Block, overview`. Some standards:

* If a noun is used in an entry, it should normally be singular; for example,
`Block`, not `Blocks`. The only exception would be if the topic is clearly about
multiple items (for instance, a topic about the regions in a theme would use the
word "regions" instead of "region").

* Be as comprehensive as possible. Most topics should have multiple entries,
since people will think of looking the topics up in various ways. For example,
in a topic about adding a field to a content type, you might have entries for
`Content type, adding field to` as well as `Field, adding to content type`.

* Make entries both for "Noun, verbing" and "Verbing, noun" (example: `Content,
translating` as well as `Translating, content`). However, do not make entries
starting with the verbs "adding", "creating", or "editing" since these are a bit
too generic.

* Capitalize the first word of the first-level entry, but not the rest of the
entry (unless it's an acronym being written out, or a proper noun). Example:
`Block, placing`, not `Block, Placing`.

* Use a gerund-form (-ing) verb in preference to -tion nouns, such as
`Content, translating`, not `Content, translation`.

* When using an acronym in an index main entry, include both the acronym and
what it stands for (make two entries). Example: `Cross-site scripting
(XSS),preventing` as well as `XSS (Cross-site scripting),preventing`.

* The index entries for glossary definitions should have secondary entry
"definition", such as `Block, definition`.

See <<style-index>> or the templates in <<templates>> for instructions on how to
put index entries into your topic.

[[guideline-additional-info]]
==== Adding links and videos

There are several sections in both task and concept topics where links to
additional information can be added:

Prerequisite knowledge::
  Add links in this section to other topics within the same book that cover
  knowledge someone would need to understand before reading this topic.
Site prerequisites (task topics)::
  Most site prerequisites listed here should include link(s) to the topic(s)
  that explain how to create the necessary content, configure the site, etc.
Expand your understanding (task topics)::
  Add links in this section to task topics in the same book that would help
  solidify or broaden the knowledge covered in this topic.
Related concepts (task topics)::
  Add links in this section to concept topics in the same book that are not
  prerequisites, but which are somehow related.
Related topics (concept topics)::
  Add links to related task and concept topics in the same book that are not
  prerequisites.
Videos::
  Embed videos in this section that exactly (or nearly exactly) reproduce the
  content of the topic in video format. See <<formatting-images>> for syntax.
Additional resources::
  Add links in this section to outside materials related to this topic, which
  could include videos, articles, documentation pages, blog posts, and books.
  Do not embed videos in this section; instead, provide a link.

All outside links to resources and videos must conform to the following
guidelines:

* The page or video linked to must be primarily providing knowledge, not
  promotion or advertising.
* The page or video must be freely available, without paying, logging in, or
  subscribing to the site.
* If a video is embedded (instead of just linked) in the guide, it must also be
  captioned; ideally, linked videos should also be captioned. (Captioning makes
  a video accessible, according the
  https://www.w3.org/2008/06/video-notes[W3C Accessibility Guidelines]).
* Embedded videos must also be translatable, and the video producer must
  provide a means for incorporating translated captions into the video.
* Instructions for downloading the translatable caption file, translating, and
  providing translations to the producer must be provided when the video is
  embedded into the text, by adding this information in a README-VIDEOS.txt
  file in the source directory.


*Attributions*

Written/edited by
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] and
https://www.drupal.org/u/eojthebrave[Joe Shindelar].
