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.

• Assistant documentation

In order to make your assistant user friendly and appealing, follow the recommendations listed below.

• Keep the titles as short as possible
• Do not use numbers in step titles
• Section title limit: One line
• Minimum of one section with one input per step
• The assistant should have between three and ten steps
• Every displayed text should be available in English and German at least
• Keys of form fields should be unique in the context of one assistant
• Input keys should match the validation keys
• Section and input limit: One screen on standard mac resolution (no browser zoom)
• An assistant should be confined to one topic. If your plugin provides multiple different functionalities, create multiple assistants.
• Create an ellipsis for long step descriptions (“read more” after one line)
• Create a final page where all settings are displayed

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.

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.

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.

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.

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.

• 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.

• 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”.

• 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.

• 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.

• 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.

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