Help text standards

Where is help displayed?

Help and other explanatory texts of a module can be displayed to users of your site at four different places.

1. Short description of what the module does. It is displayed on the Extend or Modules page (in Drupal 8 or 7). It is the only text users will see if the module is not enabled yet.
2. Description on links are displayed with the links on the Configuration and Structure pages and invite users to do something.
3. Explanations on the administration pages. Ideally, this should not be needed, but if they do they are short and do not duplicate the help page.
4. Help page displayed by the Help module with three sections: What does the module do, what can users do with it, and a link to the online documentation here on drupal.org. This hook_help() text is in the my_module.module file.

Short Description

The short description is set in the description element of:

• Drupal 8: my_module.info.yml file
• Drupal 7: my_module.info file

This description is displayed in the list of available modules on the Extend (D8) or Modules (D7) page to tell site builders what the module does, before they enable it.
The description starts with a verb and should be short and concise.

Examples

• Help Manages the display of online help.
• Content Translation Allows users to translate content entities.
• Datetime Defines datetime form elements and a datetime field type.
  description: Defines datetime form elements and a datetime field type.

Descriptions on links

The description on links is set in the description element of:

• Drupal 8: my_module.links.menu.yml file

Descriptions on links are displayed on overview pages such as the Configuration and Structure pages of your site. They often invite the user to do certain tasks.
The description starts with a verb and should be short and concise.

Examples

• Cron
  Manage automate site maintenance tasks.
• Contact formats
  Create and manage contact forms.

  title: 'Contact forms' 
  description: 'Create and manage contact forms.'

Help text on administration pages

Modules can provide help text to users on individual paths (administration pages, such as setting pages, editing forms, etc.), indexed by the path to the page.
The text is displayed by implementing hook_help() in the my_module.module file.

Help text on administration pages is generally fairly brief. It is displayed either at the top of the page or in a block, depending on the version and/or theme.

You should follow the guidelines for user interface text in general: https://drupal.org/node/604342, and in particular:

• Keep introductions as short as possible, and don’t describe options in detail. Ideally, no introduction should be necessary because the screen and its behavior should be intuitive.
• Do not describe default user interface usage/behavior (drag-and-drop etc.).

The format of the path where the help text is displayed - defined in the case element - is different between Drupal 7 and 8.
For Drupal 8, use the Drupal route as configured in my_module.routing.yml

Examples

// Drupal 7 
case 'node/%/revisions': 
  return '<p>' . t('Revisions allow you to track differences between multiple versions of your content, and revert back to older versions.') . '</p>'; 

//Drupal 8 
case 'node.revision_overview': 
  return '<p>' . t('Revisions allow you to track differences between multiple versions of your content, and revert back to older versions.') . '</p>'; 

Help page

Modules can also provide text for an overview help page by implementing hook_help() in the my_module.module file. A special path (for example 'admin/help#modulename' in Drupal 6 and 7) or route (e.g. 'help.page.modulename' in Drupal 8) should be used to define this page. This help hook depends on the Help module to display the page.

See the code example for details of the function itself.

The overview help page should follow a standard structure.

1. About section, giving a brief overview of what the module does, starting with text like "The Foo Bar module [verb]", and finishing with a standardized link to the module's online documentation.
2. Uses section, giving details of module functionality and explaining what users can do, and links to the URLs where each specific functionality can be accessed.

You should follow the guidelines for user interface text in general: https://drupal.org/node/604342, and in particular:

• Capitalize the name of the module, because module names are proper nouns.
• Make sure that titles of links to administration pages and tabs are identical to the page and tab titles.
• Do not refer to Drupal but rather to your website or similar, because the module might be used in other distributions and the user might not be aware that they are using Drupal.

Coding standards:

Headings

• Use an h2 element to indicate major sections of your help page.
• Should your sections contain subsections, Use an h3 element to indicate each subsection.
• Do not skip heading levels. An h2 should be followed by another h2, or an h3.

Links

• Links in the help text use placeholders that start with a :
• Drupal 7: with the url() function
• Drupal 8: with\Drupal\Core\Url (because Drupal::url() has been deprecated.)

Arrays

• As of Drupal 8.3, we are using the short array syntax provided by PHP 5.4. See #2135291: [Policy, no patch] PHP 5.4 short array syntax coding standards for Drupal 8 for details.
• Note the required comma in the last line of a multi-line array.

Example

use Drupal\Core\Url;


t('In order to translate content, the website must have at least two <a href=":language">languages</a>. When that is the case, you can enable translation for the desired content entities on the <a href=":translation-entity">Content language</a> page. When enabling translation you can choose the default language for content and decide whether to show the language selection field on the content editing forms.', 
[
  ':language' => Url::fromRoute('entity.configurable_language.collection')->toString(),
  ':translation-entity' => Url::fromRoute('language.content_settings_page')->toString(),
  ':language-help' => Url::fromRoute('help.page', ['name' => 'language'])->toString(),
]) 

Notice the use Drupal\Core\Url; in the beginning. It makes it possible to use global Drupal routes if you for example want to link to an admin page.

See below for an explanation about links and a detailed example of a help page for Drupal 8 and 7.

Drupal 8 note about url() and routing

Converting url() in D7 to \Drupal\Core\Url in D8

The url() function is deprecated in Drupal 8 so changes are required when porting a module from Drupal 7.

1. For full URLs, such as https://drupal.org/documentation/module/my_module -- nothing changes.
2. For URLs to other modules' help files, replace
   

   // Drupal 7 
   url('admin/help/foo_module')

   with

   // Drupal 8
   \Drupal\Core\Url::fromRoute('help.page', ['name' => 'foo_module'])

3. For URLs to other admin pages, you need to know the "route machine name" of the URL to use it in the \Drupal\Core\Url function.
   For instance, if you have a link to this Views admin page in your Drupal 7 module,

   // Drupal 7 
   url('admin/structure/views')

   then you find the route machine name in Drupal 8 in the Views UI in the /core/modules/views_ui/views_ui.routing.yml file

   entity.view.collection: 
     path: '/admin/structure/views'

   This defines the machine name for the path admin/structure/views page as "entity.view.collection", so you can convert the url() function call in your Drupal 8 as

   // Drupal 8 
   \Drupal\Core\Url::fromRoute('entity.view.collection')

Linking to help pages

Why is there a difference between linking to admin/help/module and admin/structure/views URLs?
The route entry in help.routing.yml for the admin/help/(module_name) pages is:

help.page: 
  pattern: 'admin/help/{name}' 

If you want to make a URL for the Field module help, you need to set "{name}" to "field", which is the machine name of the Field module:

\Drupal\Core\Url::fromRoute('help.page', ['name' => 'field']) 

If you need to make a link to a similar path that has variables in the "pattern" line, you can follow the same rules.
For instance, from views_ui.routing.yml again:

views_ui.edit: 
  pattern: '/admin/structure/views/view/{view}' 

This means that the URL call for admin/structure/views/view/my_view_name is:

\Drupal\Core\Url::fromRoute('views_ui.edit', ['view' => 'my_view_name'])