Skip to main content Link Search Menu Expand Document (external link)
Chris Wood

How to write a support article

Some tips and suggestions

Follow these instructions to create a simple, easy-to-follow support article.

1. Write a scannable heading

  • Your readers may be trying to find the right article from a list of alternatives so a good heading can help them find the right information more quickly.
  • Use a heading that starts with a verb. The reader usually wants to do something.
  • Creating a collection of articles? See if your headings can follow a similar structure for faster scanning.

2. Opening statement

  • Start the article with a statement that explains the purpose and value of the content.
  • After reading the statement, your reader should be clear on what outcome they can expect from following these instructions.

3. Alerts

As users may well be scanning the page at speed, using alert boxes draws their attention to important information.

If you need to use more than one box, follow the order of impact they will have:

  1. Warnings first
  2. Information second
  3. Tips last

Warning boxes

Use these to alert the reader to a change they can’t undo.

Information boxes

Use these to give the reader useful context.

Tip boxes

Use these to add non-essential information that may help someone save time.

4. The instructions

  1. Write a sentence to introduce the instructions. This sentence might include
    • assumptions about actions the reader needs to have completed
    • or other requirements that need to be met before they start.
  2. Write one step for each individual action. Aim to start each instruction with a verb.

Example

After you receive your confirmation email:

  1. Go to http://example.com/code
  2. Enter your access code and then select Continue.
  3. Sign in with your email address.
  4. Select Use a code.

5. Include a visual

As people will often be looking for help with a UI or something in the real world, it’s often helpful to include some kind of visual. These could be:

  • an annotated image
  • a gif or video that shows a process the reader has to complete

To support users of assistive technologies, include alt text on all images.

6. Finish with links to next steps or related content

Example

At the bottom of a support article about creating an account, you might have a list like this:

Learn more:

  • Start using your account
  • Update your profile

Adapted from Writing helpful help