Guideline Writing

In this document we share some pointers for writing good guidelines and keeping them consistent with the rest.

Introduction text

Place an intro text at the beginning of the component's main page (i.e. the "Examples" tab), giving an easy-to-scan and easy-to-digest brief to help understanding its purpose — useful for all parties working with this component, including devs.

Pro Tip: try starting your sentence with The component's purpose is… or It enables marketers to… to get yourself on the right track.

Example:

The Action List component displays a list of related action items, enabling marketers to choose an action in context with immediate effect […]

Additionally, including some example use cases and listing some notable distinctions can also help.

Example:

[…] for example, picking a personalization token to insert into a text field.

Action items can be filtered, grouped, and have various states (e.g. disabled, or selected).

• Do: Use active voice.

  Use radio button to display each item in a list of options, where marketers have to make a single choice.

• Do: Use passive voice with persona.

  Radio buttons are used to give marketers a way to select one single choice out of a list of options.

• Don't: make the intro text longer than 3–4 sentences.

  Radio buttons are used for selecting one single option out of a group of several related options, like alternatives or choices.

Guidelines document

Guidelines are documents which help designing with the component. These are mostly useful for designers, so we display them slightly separated from the main content (i.e. on the "Guideline" tab).

Structure

Describe atoms and other components that build up this component. Add an illustration to make it clear which part a specific designation refers to. Naming parts should generally follow naming of the atoms and be aligned with naming scheme in code. Also describe any additional design attribute that is not apparent from the illustration or from the live version of the component.

• Do: Start with [Component name] consists of: and add a numbered list.

Radio buttons consists of:

1. Radio Button group label
2. Interaction field
3. Radio Button label

Additional design attributes:

• Aligned vertically: it clarifies the connection between the options but separates the items visually.

Best practices

Write out everything that you think is important of the component, mostly focusing on the behavior. Later sort overlapping instructions, fine-tune the grammar. Best practices should be grouped according to the structure parts, where it makes sense (more than 10 guidelines for a single part or component)

• Do: Start with [Component’s name] should: and finish the sentence in bulleted list.

Radio buttons should:

• Let the user select only one choice from a list of options.
• Have their labels positioned on the right side of the selectors.
• Let users select an option by clicking on either the button itself or its label.
• Have a clear group label that describes what the selection is about.

• Do: Start with Try to avoid: and finish the sentence in bulleted list.

Try to avoid:

• Sorting items in alphabetical order. It couldn’t be localized due to its language-dependency.
• Large number of options. Use Select component instead.
• Overlapping choices. e.g. Age of contacts: 0-18, 18-35 - Where will be 18 years olds sorted?

Clarify confusing concepts

This helps fresh users distinguish components that are similar in a manner.

Clarified concepts

• Radio button: Select a single choice from limited set of options.
• Checkbox: Select or deselect even multiple choices from limited set of options.
• Select: Select a single item from an expandable drop down-list.

Content guidelines

A wrongly formulated instruction, a needlessly long description or bad punctuation could cause as much confusion as a poorly selected component. Write detailed guidelines for making content and provide positive and negative examples if possible.

Radio button labels should:

• Start with a capital letter.
  ✓ Option 1
  ✗ option 1

Visual guidelines

Provide numbered and explained illustration if it helps understand the component’s arrangement, behavior. Put the explanation short, let the visuals speak for themselves.
Example:

• Do: For explaining a concept use stylized illustration that highlights only 1 information.
• Do: For presenting a component part by part, build it in Sketch and place numbered dots on the important areas. Explain the function of the parts in numbered list right after the illustration.
• Don’t: Use messy screenshots for illustrating a concept or presenting a component.

Writing style

Lists

Give context to a list with a leading sentence. This sentence should end with a colon.

A component should:

• Do this.
• Do that.

Sentence-like list items should be punctuated, even if the sentence is really simple.

• This first list item is well written. Wow!
• Second list item.
• This third.

Word list items should not be punctuated.

• First
• Second
• The Third

Spelling

• Use American spelling. You can still use the British "way of writing", just make sure it looks American. Mind words like personalization, color, organize, gray, etc.

Capitalization

• Capitalize component names in a sentence like a proper noun, to signify you're talking about a specific thing. (i.e. like a book title)

Use the Button to enable the marketer to trigger an action.

• Section headings (e.g. h2, h3) in a guideline page should have sentence headings.

Abbreviations

For Latin abbreviations, use these formats:

• e.g. (not eg.)
• i.e. (not IE)
• etc. (not et.c.)