Writing Help Documentation
Helpful documentation rests on two main pillars: structure and accuracy. The faster we can help someone find an answer to their question, the faster they can get back to what they actually want to be doing.
We want to empower every Zapier employee to update our help docs if they see a hole or potential improvement. To keep our voice unified and our structure clear, we follow some simple guidelines.
Help documentation exists so that our customers can solve problems and discover what’s possible with Zapier. Our docs cover a range of topics:
- Baseline docs exist for every Zapier integration. They cover:
- Which triggers and actions we support for an app
- How to authenticate the app with Zapier
- Popular Zaps to build with the app
- Common problems you might run into with the app
- Getting started content like what Zapier is, how it works, and what specific terms mean.
- Features of Zapier itself, like filters and the Task History.
- Account explainers around how to change your password, upgrade your account, and more.
- Troubleshooting tips that aren’t specific to a single integration.
- Advanced tips best suited for people who are familiar with Zapier already.
If your documentation doesn’t fit comfortably into these categories, /help may not be the appropriate home. Clutter can confuse people who are in search of a simple answer. Consider stashing docs that don’t quite fit in one of our internal tools.
Voice and Tone Guidelines
When someone visits our help docs, they’re curious at best and frustrated at worst. Write for understanding, add structure so your doc is easy to skim, and help your reader solve their problem as fast as possible.
Here are some tips on writing helpful documentation:
- Use a friendly, casual tone. Pretend you’re working the information desk at a train station. Explain next steps with a smile. Stay calm and your reader will stay calm.
- Use an active voice. Direct your reader. Map out their steps. Write in the second person. For example: “Next, type in your username and password.”
- Use simple, clear language. Don’t make a tutorial tougher than it needs to be. Translate tricky terms into plain language, but err on the side of over-explaining. We want our reader to succeed with our instructions.
- Avoid technical jargon. Sometimes you need to includes notes about API calls or integrity errors. But when possible, edit out daunting terms.