Assistant style guide

If you plan on implementing an assistant to help users set up your plugin, follow the rules set forth in this style guide.

Further reading

How to display information

It is ideal to use fixed places for different types of information. To decide where certain bits of information should be displayed, they need to be categorised. Stick to the following rules to facilitate interaction with the assistant and provide users with all required information at the same time.

Important

Never include links to external information, such as the manual or video tutorials. Assistants have to contain all necessary information and explanations to enable the user to carry out all settings and understand the options provided.

Exception: In case of certain technical necessities; e.g. when users have to be forwarded to markets or payment providers to enter/save/validate data there and there is no alternative solution.

Mandatory information

Some information is mandatory and needs to be visible to users at all times. Use the description sections to display explanations and introductory texts that users need to understand the task at hand.

Optional information

Some information is considered optional, e.g. because it is self-evident to certain users. In this sense, optional information can exist in the form of specifications for password requirements. However, there is also information that is not optional in the strict sense, but cannot be displayed in its full length within a step of the assistant: This applies to explanations of options users can choose from and that require further explanation.

Use text in tooltips for such explanations. The following rules apply:

  • Try to write descriptions of 20 words or less. Never exceed 50 words in one description - if you do, this may indicate that you should split up the step or section further.
  • Tooltip texts should not link to resources outside of the assistant.

Using selection controls

Consistency is important, so that users are not confused by the way they make choices within an assistant. The following rules should be applied uniformly throughout all assistants.

Radio buttons

  • Presents the user with two to seven mutually exclusive options. All options should be clearly labeled.
  • Changes a setting. The change only takes effect after the user clicks a command button.

Usage

  • Do not use for single binary choices like Yes/No questions.
    • For settings, use a single checkbox instead.
    • For actions, use a toggle switch instead.
  • When users can choose more than one option, use a checkbox group instead.
  • For eight or more options, use a dropdown list instead.
  • If the options present a scale with set intervals, use a slider instead.
  • Select a default choice. If users should be able to not make a selection, provide a button labeled None or similar.
    • Exception: If the default choice is preferred by the vast majority of users in most situations, use a dropdown list, even if there are less than eight options.
    • If there are very few options, you may also label the default option as “recommended”.

Checkboxes

  • Presents the user with a list of independent choices, of which they may select any number, including all or none.
  • Changes a setting. The change only takes effect after the user clicks a command button.

Usage

  • Use a single checkbox for single binary choices.
    • The checkbox always describes the positive choice.
  • Use indeterminate checkboxes to represent a group of checkboxes.
  • If there is no command button and changes take effect immediately, use a toggle switch instead.

Toggle buttons

  • Presents the user with exactly two options: On and Off.
  • Performs an action. The change takes effect immediately, either by adding additional steps to the assistant or additional fields in the same step.

Usage

  • If there is a command button and the change only takes effect after the user clicks it, use a single checkbox instead.

Is this article helpful?

 

Thank you for your Feedback

you can close this field now!