Voice & tone principles

Principles for clear, readable docs.

  2 minute read  

Docs, to some degree, represent the voice of your organization.

People respond well to a friendly, helpful tone that is easy-to-read.

These principles help.

Use one clear intent

Good docs help users solve problems.

Before working on a doc, understand the audience you’re trying to reach and the problem being solved.

This is called the intent and is typically expressed as as follows:

“As a <role>, I want to <solve a problem>.

Examples:

  • “As a developer, I want to back up my database.”
  • “As a novice, I want to create a doc website.”
  • “As a new writer, I want to check the readability of my content.”

Good intents helps:

  • Writers organize content and know when to stop.
  • Reviewers know the limits and scope of the article.

If you’re having trouble outlining an article, take time to consider the intent carefully.

Be brief

Modern readers are in a hurry.

They’re not reading your content for entertainment; they’re trying to solve problems.

Design accordingly:

  • Be direct and concise.

  • Write simple sentences and minimize discussion.

  • Write the simple case first; discuss complications later.

The acronym tl;dr is a useful guidepost.

Be scannable

Few people read for depth initially.

Instead, they scan webpages and try to pick out relevant details before diving deeper.

Structure your docs accordingly:

  • Use short sentences, small paragraphs, and lots of white space.

  • Minimize distractions and limit decorations (rules, frames, and blocks of color).

  • Avoid distractions, such as elements that move (animated images, autoplay videos, and so on.)

  • Move complicated or detailed discussions below summarized answers.

Use everyday language

Many industries have terms and language specific to their domains.

Don’t assume that your readers know these terms or search on them.

As an example, consider the following terms:

  • finetune
  • headunit
  • ingest
  • inference
  • upsert

Can you define them clearly? Can your readers? How about people who aren’t already using your product or service?

Instead, use plain language; define industry terms and jargon.

Show empathy

Some things are hard or complicated. Be up front about it.

At the very least, don’t be a jerk.

Don’t describe something as quick or easy when it’s neither.

Remove marketing hype and hyperbole.

Focus on objective, reproducible facts.

We’re all learning. Be gentle.

Vital statistics

  • 10 May 2024: First post for this website