Help Topic Standards

Introduction to Help Topics

As of Drupal 8.8.x, there is a new functionality in Drupal Core, where each module, theme, and install profile (core or contrib) can provide one or more Help Topics. As of 26 June 2023 (10.2.0 core) this functionality is provided by the core Help module (in earlier releases it was provided by "Experimental" Help Topics module).

The way Help Topics work is that modules, themes, and install profiles can create a subdirectory called help_topics. Inside this directory, they can provide one or more Twig files containing their help topics; these files should be named something like mymodule.topic_id.html.twig. Each file starts with a few lines of "front-matter meta-data" (more on that below), and the rest of the file is rendered using Twig to create the body of the topic. The topics that are marked in the meta-data as being "top level" are listed on the main Help page at admin/help; other topics can be found by following "Related" links from the top-level topics (created from the "related" meta-data).

If you are creating topics for a contributed module/theme/distribution, you will need to put them into your project's help_topics subdirectory so that they will be recognized as topics.

One other thing to note is that the "Related" relationship is automatically bi-directional. So if topic A lists topic B in its "related" meta-data, then you will see topic B in the "Related topics" section on topic A, and vice versa.

Help Topic Syntax Example

---
label: 'Viewing and managing actions'
top_level: true
related:
  - user.security_account_settings
---
{% set actions_link_text %}
{% trans %}Actions{% endtrans %}
{% endset %}
{% set actions_link = render_var(help_route_link(actions_link_text, 'entity.action.collection')) %}
{% set views_topic_link = render_var(help_topic_link('views.overview')) %}
<h2>{% trans %}Goal{% endtrans %}</h2>
<p>{% trans %}Configure one or more actions on your site.{% endtrans %}</p>
<h2>{% trans %}What are actions?{% endtrans %}</h2>
<p>{% trans %}<em>Actions</em> are tasks provided by modules that can be executed by the site, such as unpublishing content, sending email messages, or blocking a user. Modules can trigger actions when specific system events happen; for example, when new content is posted or when a user logs in. Some actions are <em>simple</em> and require no configuration; others are <em>advanced</em> and can be configured. Actions can be used in views for bulk operations; see {{ views_topic_link }} for more information about views.{% endtrans %}</p>
<h2>{% trans %}Steps{% endtrans %}</h2>
<ol>
<li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Configuration</em> &gt; <em>System</em> &gt; {{ actions_link }}.{% endtrans %}</li>
<li>{% trans %}Select an action type from the drop-down list and configure it.{% endtrans %}</li>
</ol>

See the Help Page for detailed information about the help text standard.

Standards for Writing Help Topics

Dividing your Help Into Topics

Good technical documentation is organized around the tasks a user would do, and has a clear separation between tasks and concepts. In addition, each task is ideally in a separate section of the documentation. So, when thinking about what help your module, theme, or profile needs, you should first think about what tasks a user of your extension would need to do, and then about what background information they would need in order to do each task.

Once you have figured that out, you are ready to create Help Topics. There are two types of topics. Each task you have defined should be put into its own Task topic. If you have multiple task topics, they can be grouped into a help section by making a Section topic, and listing the Task topics as "Related" to the Section topic. Background information that pertains to just one task should be put into that Task topic; background information that pertains to multiple tasks should be put into the Section topic.

Also note that every topic you create must either be "top-level" (see below) or must be marked as "related" to a top-level topic. If you are documenting a contributed module, you can mark your topics as "related" to a core top-level topic (but make sure it's in a module that your module is depending on!).

General Standards

• All text in the body of topics needs to be wrapped in {% trans %} ... {% endtrans %} so that it can be translated.
• All links should be made using the help_topic_link() and help_route_link() functions (see above example).
• When describing navigation (usually as part of the Steps in a task topic), use a format like: "In the Manage administrative menu, navigate to Structure > Content types." If it is possible, make the last part of the navigation into a link to the page that you would end up on (this is not always possible; for example, if you are telling someone to select a particular content type as part of the navigation, or if the page belongs to a different module than the one that is being documented).
• Help topics should be written in complete sentences.
• Be as direct as possible: so tasks should be written in imperative mood ("Do this." not "You could do this.")
• Avoid words like "please" and "simple" and "obvious".
• Follow the UI text standards at https://www.drupal.org/node/604342 and https://www.drupal.org/drupalorg/style-guide/content
• In general, link to other help topics rather than duplicating information that is in other help topics. For example, in a topic that is about configuring the Search module, if one of the steps is placing a block, just say to place the block and link to the block placing topic (don't explain all the steps needed to place a block).
• There are two ways to link to a help topic: (a) put it in the Related Topics section ("related" metadata; see details below), or (b) within the text, make a link to the topic (see above example for both of these).

Parts of a task topic

Here are the parts of a task topic (refer to the example above):

1. Title: A description of the task you can accomplish, starting with an -ing verb, such as "Setting permissions per role". This goes into the front-matter section ("label" element) at the top of the topic Twig file
2. Top-level: Every topic needs to either have the front-matter element saying it is "top_level" (top_level element), or needs to be Related to a top-level Section topic. Top-level topics are listed directly on admin/help.
3. Related topics (Optional): List topics related to this task, such as Section topics or related tasks. These are listed in the front-matter meta-data section ("related" element) at the top of the topic Twig file.
4. Goal: (should be an h2 heading called "Goal", at the top of the body section) In 1-3 sentences, describe the goal of the task, and possibly why you would want to do it.
5. What is/are...: (optional) If there are terms that need to be defined, or background information that someone would need to know to accomplish the task, you can add one or more sections, under h2 headings starting with "What is/are...". However, if there are multiple tasks related to this background information, put this information into a Section topic instead.
6. Steps: (h2 heading) The steps needed to accomplish this task. Usually should contain a numbered list of actions to take.
7. Additional resources: (optional h2 heading) One or more links to outside material (documentation on drupal.org, videos, etc.) that expands on this topic. The preferred place to link would be a page inside of the User Guide. Make sure all links have link text showing the name of the item being linked to. Only include materials directly relevant to this topic, and only if there is not another Help Topic that covers the information (in which case the link would instead go in the Related topic meta-data).

Parts of a section topic

Here are the parts of a Section topic:

1. Title (as in a Task topic). Typically it would be something like "Managing blocks" for a Section topic.
2. Related and top-level (optional, as in Task topic). Section topics must be top-level, so that we don't end up with a large hierarchy of topics.
3. What is/are...: (optional, as in Task topic)
4. ... overview: (h2 heading, such as "Managing blocks overview") 1-3 sentences describing the tasks related to this section, ending with this sentence: "See the related topics listed below for specific tasks."
5. Additional resources: (optional, as in Task topic)