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

On this page

2.4. Style Guide for the Writing Phase

Last updated on
11 January 2024

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 Section 2.2, “Writing Good Documentation”, and especially if you are writing a task topic, Section 2.3, “Following the Scenario”. If you want to think ahead, you can also look at Section 2.5, “Style Guide for the Editing Phase”, but this is not required.

The guidelines here are partially based on:

On this page:

2.4.1. 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 Section 1.2.2, “Paragraph and list formatting” for the mechanics of putting lists into your topic.

2.4.2. 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.

2.4.3. 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.

2.4.4. 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 Section 1.2.6, “Making index entries” or the templates in Section 3.3, “Topic templates” for instructions on how to put index entries into your topic.

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 Section 1.2.7, “Including images and videos” 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 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 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-writing.asciidoc

Help improve this page

Page status: No known problems

You can: