Writing for Developers
At Zapier, developers aren’t our primary audience, but they’re an important one. In fact, many developers are users of Zapier because nobody wants to write more code than is needed–that’s why Webhooks and Code are popular apps. But perhaps most notably, Zapier apps are usually built outside of Zapier. That means someone from another SaaS company connects their API to the Zapier platform.
When we say “developers”, we mean anyone who wants to integrate their app with other apps. A Zapier developer is not always an engineer: they may be a product manager, a marketer, or any other person with enough technical skills to build against our developer platform. We provide more nuance to what a developer is in the Partner Definitions section of Writing for Partners.
Anything we write for developers should either:
- Teach them something new
- Inspire them to think about new possibilities
Many times we’ll be able to achieve both within the same piece of content.
Three Approaches to Developer Content
There’s not a single way to write to developers, because their needs change depending on what they’re trying to accomplish. Sometimes a developer just needs an answer and other times they’ll want context—there’s a big difference.
We break it down into three approaches:
- Hold my hand. Walk through the idea step-by-step, providing as much detail as you can. Think tutorials or getting started guides.
- Show me the gotchas. At a high level, give your reader best practices and point out land mines.
- Feed me facts. Dive into details, but don’t focus on a specific application. Think API references or documentation.
Your documentation will be a mix of all three of these approaches, and you can use any of them elsewhere, such as blog posts.
Regardless of the approach and type of content, keep these guidelines in mind:
- Do be friendly. Writing about technical topics is not an excuse to become a robot. Your words can be both whimsical and accurate.
- Do show code. You’re writing for people who write code. Samples are encouraged!
- Do assume some knowledge. You can’t start at the absolute basics every time. Be clear about what you think the reader knows, then link out to other documents for deeper background.
- Don’t punt on crucial context. As a balance to assuming knowledge, you should include essential information within your document. Don’t link off to another place on your site for background without also providing some context within the document itself.
- Don’t use isolating language. Developers come from all backgrounds and locations. When you use analogies that lean toward one gender or nationality, you make it harder for others to understand and feel included.
While not quite at the level of guidelines, here are some other things we look for, especially in blog posts and tutorials:
- Watch the “ings”. Many headlines are passive, like Building a Robot. A better choice: How to Build a Robot
- Adjectives are fabulous. While we’re improving that headline, feel free to get creative. How to Build a Wacky Robot is even better.