One of the most common pieces of feedback I give to design system teams about their documentation is this: write using the active voice.
In this post I’ll explain what the active voice is and why it matters.
What is the active voice?
Unless you write for a living, then trying to recall the difference between active and passive language from high school English class might be a bit like asking someone like me - that is, not a mathematician - to recite the Pythagoras theorem. So let me explain.
The active voice makes it clear who is doing what.
For example, “You are reading this blog post” is active, whereas “This blog post is being read” is passive.
Examples of the active and passive voice
Let’s look at some examples of how active and passive language might appear in design systems.
| Active voice | Passive voice |
|---|---|
| You can use an icon with this button, instead of a text label. | Icons can be used with this button, instead of a text label. |
| The design system team reviews contributions against the component acceptance criteria. | Contributions are reviewed against the component acceptance criteria. |
| We last reviewed this documentation in October 2021. | This documentation was last reviewed in October 2021. |
How using the active voice improves design system documentation
There’s lots of research to show how using the active voice makes content clearer and more readable in general.
Organisations that recommend using the active voice include:
And there are some specific benefits to using the active voice in design systems.
The active voice is easier to read and remember
If you’ve ever watched someone trying to install or use a design system in user research, you’ll know that getting people to read your documentation at all is no mean feat.
When we’re writing for busy designers and developers, it pays to do all we can to make our content as easy as possible to digest.
Research on whether the active voice is always easiest to read is mixed.
But my first-hand experience of observing people reading documentation in user research says that it's generally easier to parse - and there's some evidence to support this.
Jan Spyridakis, quoted in the GOV.UK Content Manual, explains:
"Not only do readers move more quickly through active voice text, but they prefer it and feel more familiar with it. Readers may even encode passive voice text in active voice."
Instructions written in the passive voice are easy to miss
A huge benefit of using the active voice in documentation is that it removes ambiguity about who needs to do what.
"The spellcheck attribute must be set to false on email address fields" gives no information about whose job it is to do that.
Passive statements about things that need to happen are easy to overlook. Instead, we can use the active voice to give a clear instruction:
"Set the the spellcheck attribute to false on email address fields" tells a developer reading the documentation that this is something they need to do.
Writing in the active voice encourages us to be more specific
Writing passive sentences lets us avoid giving details and making specific commitments. This, in turn, makes it easy to unintentionally break our promises.
For example: "Your pull request will be reviewed within a week" doesn't say who will review the pull request.
Making this sentence active forces us to assign someone - or a group of people - to the task. This helps design system users to keep us accountable, and builds trust.
In my experience, this often prompts important conversations about whether the commitments we're making are actually realistic, and make necessary adjustments to our processes.
Want to learn more about writing for design systems?
I’m putting together a half-day, online training course on how to write clear documentation for design systems. I’ll be running it later this year.
If you’re interested in attending the course, email me at amy.l.hupe@gmail.com and I’ll add your details to a waiting list.