I’m at Write the Docs today in Budapest and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Jessica comes from a humanities background and about a year ago started teaching herself to program. She works for Majestic SEO and, when they found she was learning to program, immediately set her to work on the product’s documentation.
When she started out she wasn’t really sure what she was doing. Tone is about feelings and Jessica didn’t really know how to add that in to documentation. She found that you can’t seek out concrete rules for tone, it’s more of an art than a science. The most important thing to remember, though, is to use tone as a reinforcement of your brand’s voice; just don’t make it too sleazy.
Tone shows your users who you are. It broadcasts what you wish users feel about you. It can also communicate who your intended audience is and what your expectations are for how they will, or might, interact with your product. Finally, it indicates the level of interactivity you’re willing to maintain with your clients or users.
Part of talking effectively to your audience is accurately assuming who your readers are. Setting those expectations from the outset involves looking at skill level, whether they’re an individual or organization, commercial or non-commercial. It’s so easy to get this part wrong. Misjudging your audience can limit that audience through a tone that’s at the wrong level. You can also exclude potential users through the use of culturally limited references. Overall setting expectations is about asking what tone you want users to carry through your product.
Tone is also about the level of creativity your users must take. For example, are you inviting them to try and break something? Or, are they needing to conform to a level of professionalism or specific niche.
We can also use tone to open up the vision or aspirations for our users. Tone can encourage users to set a broad, but not too broad, scope with vast creative potential. What gets messy is setting multiple levels of user expectations.
Before you set the tone for interaction you can run through a set of helpful questions. What kind of resources are you making available for user support? Are you building a community? What level of transparency are you aiming for? All of those things can help set the proper tone.
Jessica highlighted Buffer’s API documentation as a great example of tone. They set a very personal tone that helps direct users where to contact them. It’s lots of “you” and “we” throughout.
There are times, though, when you need to divorce from your voice. When your audience for documentation and the main product diverge. Or, when the branded tone suggests a level of support or interactivity you’re unable to support. You can also dilute your voice a bit in documentation. It doesn’t have to be an either/or situation.
Ultimately, when you’re writing you have to ask who your users are, what you expect them to be doing, and how much interaction you want to promise them.