Skip to main content
All CollectionsInternal
Help Center Best Practices
Help Center Best Practices

Learn how to write help-center articles, cookbooks, recipes, HOWTOs, and guides that area easy to consume, compose, and maintain.

Chris Ramlow avatar
Written by Chris Ramlow
Updated over 3 years ago

Problem

You would like to create a new Help Center article, but you first want to ensure it will be easy to consume, compose, and maintain.

Solution

Consider each of the Help Center best-practices discussed below.

Discussion

Use the provided template

See How to write a help-center article for the step-by-step guide.

Keep them short and focused

Consider breaking down complex problems into smaller ones, and writing a separate article for each step. You can then link these articles together in a separate "workflow" article to capture the whole solution.

Keeping your articles short and focused encourages their reuse and simplifies their maintenance.

Design for busy readers

Don't expect your audience to care about your Discussion. Many readers will just want a quick Solution to their problem so they can get back to a larger goal.

Design for re-use

Don't expect your readers to memorize your Solution. Ideally they'll come back to your article and re-use the Solution any time they face a similar problem again.

Design for easy discovery

Don't expect your audience to read your articles in advance of having a problem, nor be familiar with how the articles might be structured. At best, they'll be aware of the Help Center as a resource, so they need to be able to find your article by via a simple keyword search. It's important for you to use their lingo, if not in the article title, then in the "tag" section.

Use visuals

Whenever appropriate, use screenshots and/or animated GIFs for multi-step workflows.

  • Leverage on-screen appropriate markup to draw the reader's attention to the right element. Always double-check text/media spacing for readability.

  • Use a drop shadow for all screenshots, which will make them pop. The following settings are recommended: opacity 25%, offset 0pt, blur 20pt.

  • Think carefully about what to include in your screenshot/animation. Show too much, and it might get out-dated sooner. Show too little, and the context may be hard to understand. Finding the right balance will make your article more durable while retaining its effectiveness.

See Also

Did this answer your question?