Tour text standards

Last updated on
25 January 2017

This page contains some initial guidelines for writing text for tours of the Drupal admin UI using the Tour module.

Style

General

  • Start the tour with a general modal (not linked to any element) for a general introduction.
  • Imagine the most basic task possible and write to that. Don’t try to cover every use case.
  • Remember that your audience is a new user, so assume no Drupal knowledge.
  • If possible, keep the tour to fewer than 8 tips.
  • If possible, keep to a single sentence per tip of less than 25 words.
  • A tour tip is not UI text. Don’t duplicate the UI text.
  • A tour is not documented. You can link to documentation at the end if you think it’s useful.
  • Doesn't explain stock Drupal page elements such as breadcrumbs or pagers.
  • Use links where useful and ensure they will never break.
  • Avoid complex tour tip selectors such as :first-child or :nth-child(n) as these at present cannot be tested via simpletest. Instead, add classes into the body to make the selectors easier to understand.

Example

id: dblog
module: dblog
label: 'Database log'
langcode: en
status: 1
routes:
  - route_name: dblog.overview
tips:
  dblog-intro:
    id: dblog-about
    plugin: text
    label: 'Recent log messages'
    body: 'System events such as errors, failed login attempts and content updates are stored as messages in the site's database. On the <em>Recent log messages</em> page you find a chronological list of recorded messages that you can filter and view. You should check the log messages on a regular basis to ensure the site is working properly'
    weight: 1
  dblog-filter:
    id: dblog-filter
    plugin: text
    label: 'Filtering messages'
    body: 'Click on <em>Filter log messages</em> to filter the log messages by <em>Type</em> (usually the name of the module that generated the message) or <em>Severity</em> (emergency, critical, notice, etc).'
    weight: 2
    attributes:
      data-class: 'dblog-filter-form'

More information

Guidelines for developing tours

Help improve this page

Page status: No known problems

You can: