Write The Docs EU — Jessica Rose — Tone in Documentation

Jessica Rose

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Most Important Thing: Reinforce your brand’s voice, but don’t make it sleazy.

How do you want your users to feel about you?

Tone can also:

  • communicate your intended audience.
  • communicate your expectations for how they will (or might) interact with your product.
  • indicate the level of interactivity you’re willing to maintain with your clients or users.

Be willing to make updates or changes.

Communicating audience expectations

  • skill level
  • level of investment
  • individuals or organizations
  • commercial or non–commercial

Common problems with user expectations and tone

  • Misjudging your audience.
  • Limiting your audience through tone of the wrong level.
  • Writing for yourselves, rather than your users.
  • Using culturally limited references can exclude potential users.

Setting expectations with tone.

Level of Creativity

  • What kind of limits, if any, do you want to set?
  • Do you expect user to confirm to a level of professionalism or a specific niche?
  • Are you inviting them to try and break something?

Aspirations for Users. Encourage ten to do more.

Challenges in Setting Expectations for use through tone

  • Setting too narrow a scope for expectations is going to limit your more creative potential users
  • Setting too wide a range of expectations for your users is going to panic lower–level users.
  • Trying to set multiple levels of user expectations can get messy.

Setting communication expectations

Setting the tone for interaction

  • What kind of resources are you making available for user support?
  • Are you building a community?
  • How accessible do you want to be to your users?
  • What level of transparency are you aiming for?
  • Public or private communications?


  • She’s a fan of Buffer because of their tone. For example, their “Questions & Problems” section. Echoes their brand awareness and transparency.
  • Ember.js also has great tone and documentation.
  • Wikipedia
  • CoffeeScript. Their branding is their documentation. Not as accessible. Not very much comforting language, or a personal connection.

When is it important to divorce from your branded tone?

  • When your audience for documentation and main products diverge.
  • When the branded tone is inappropriate.


  • Yelp has a distinct, happy branded voice. Very cheerful, bouncy, yet patronizing. Their developer documentation is dry.

Divorce or dilute?

  • Facebook has a unique branded voice. “Hey, we’re Facebook, we have your family!” Documentation is slightly watered down to break out of the Facebook stalker bits.


  • Who are my users?
  • What do I expect them to be doing?
  • How much interaction do I want to promise?

Published by

Bryan Villarin

Bryan works at Automattic. Cat whisperer. Sometimes, a photographer and card magician.

One thought on “Write The Docs EU — Jessica Rose — Tone in Documentation”

Talk to me, Goose

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s