On this page
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
- Follow the style guidelines for Interface text.
- Keep it simple.
- Use "-ing" verb mode for the tip label. So "Viewing log messages" instead of "View log messages".
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
Help improve this page
Page status: No known problems
You can:
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion