Voice and tone are the foundation of clear, consistent, and user-friendly content, whether you’re writing knowledge base articles, UI text, conversational AI responses, troubleshooting instructions, documentation for another product, or in-product guidance. A well-defined voice and a purposeful tone help you communicate with clarity, support your users effectively, and deliver content that feels cohesive across every touchpoint.
Voice is the personality that stays stable. Tone is the attitude that adapts. Understanding the difference and applying both correctly ensures your content is consistent, accessible, and appropriate for every context.
Where these guidelines apply
Use these voice and tone standards across any content you create:
Getting started guides
Feature instructions and walkthroughs
Troubleshooting steps and workflows
FAQs, how-to sections, and usage scenarios
Use case–driven articles
Feedback responses and customer communications
Release notes (direct, concise, no marketing fluff)
In-product guidance, such as tours, dialogs, and tooltips
UI text and microcopy
AI chatbot and AI agent responses (including system messages, clarifying questions, confirmations, and fallback responses)
If it reaches a user, directly or through an AI assistant, these rules apply.
What is voice?
Voice refers to the consistent personality or character of the content in the knowledge base. It reflects who you are as a brand and remains consistent across all documentation, regardless of the author or content type.
Principles of an effective product voice
Clear: Prioritize simplicity. Use plain language, avoid jargon, and focus on helping users understand quickly.
Not recommended: "Utilize advanced functionalities to systematically organize content."
Recommended: "Organize your articles with just a few clicks."
Helpful: Provide solutions proactively. Guide users with step-by-step instructions and actionable advice.
Not recommended: "It is recommended to configure the custom domain as per the standard guidelines."
Recommended: "Follow these steps to set up your custom domain."
Confident but approachable: Use direct language, active voice, and positive framing. Be professional without being overly formal or distant.
Not recommended: "Users might find the dashboard somewhat intuitive for knowledge base management."
Recommended: "Manage your knowledge base efficiently with our intuitive dashboard."
Examples of voice
Recommended: "You can easily manage your knowledge base settings."
Not recommended: "The user is able to manage knowledge base settings."
The preferred example is direct, user-focused, and easy to understand, reflecting a clear and helpful voice.
What is tone?
Tone refers to the emotional nuance or attitude conveyed in writing. While the voice remains consistent, the tone adapts based on the context, audience, and purpose of the content.
Tone’s flexibility
Tone shifts depending on factors such as:
Content type: Knowledge base articles (neutral), release notes (encouraging), troubleshooting guides (reassuring).
User’s emotional state: Calm and clear when users face issues; friendly and engaging during onboarding.
Purpose: Instructional tone for guides, informative tone for updates, supportive tone for error messages.
Examples of tone
Neutral tone: Use a straightforward and objective style for instructions.
Not recommended: "Kindly consider clicking the save button if you think your changes are final."
Recommended: "Click Save to apply your changes." (Simple, factual instruction)
Supportive tone: Be clear and solution-oriented, especially when addressing issues.
Not recommended: "Unfortunately, this error might occur sometimes. You may try something else."
Recommended: "If the issue persists, follow these troubleshooting steps to resolve it." (Clear and solution-oriented)
Encouraging tone: Use positive and informative language when introducing new features or guiding users.
Not recommended: "You can try using the new features if you want."
Recommended: "You can now access the new features to enhance your workflow." (Positive and informative)
Key differences between voice and tone
While voice and tone are closely related, they serve distinct purposes in technical documentation. Here’s a comparison to highlight their key differences:
Aspect | Voice | Tone |
|---|---|---|
Definition | The consistent personality of the content reflects your brand identity. | The emotional attitude or style that changes based on the situation and the audience’s needs. |
Consistency | Always the same across all content to maintain a unified brand presence. | Changes depending on the context, such as being more supportive during troubleshooting or more informative when introducing new features. |
Example | "You can manage your knowledge base settings confidently and efficiently." (Consistently clear, helpful, and confident language) |
|
Why voice and tone matter in technical documentation
Consistency: A unified voice builds trust and helps users feel confident navigating the documentation.
Clarity: A clear, consistent voice ensures instructions are easy to follow, reducing user confusion.
User engagement: Adapting tone appropriately makes content more relatable and accessible, enhancing the user experience.
Quick reference summary
Voice = consistent personality: Clear, helpful, confident.
Tone = adaptable emotion: Neutral, encouraging, reassuring, based on context.
Keep the voice consistent; adjust the tone as needed to suit the situation.