Voice and tone guidelines
At Grafana, we like our company to sound like a real person.
Voice and tone reflect your attitude and how you convey information. Word choice, use of bold or italic emphasis, punctuation, and grammar all affect your voice. The tone you choose reflects the urgency of your message and can therefore change depending on the situation.
Consult the following voice and tone guidelines when you write technical documentation.
Project confidence
You know the subject matter better than anyone. Let your style reflect your expertise. Write in an authoritative tone to evoke confidence in your reader.
Be conversational
Write in a natural and conversational style with language that reflects a positive and friendly tone. Be informative and helpful by using simple, easy-to-understand words and sentences. Keep your language simple and straightforward.
Tone
A casual tone is accepted in UI copy and supporting material compared to traditional business writing.
As long as they allow for shorter sentences, you can use the words and, but, and so in moderation.
Use contractions like isn’t for is not to help to convey an informal tone.
Task completion
Provide the user with just enough information to complete a task. Inform the user that something has happened as expected once the task is completed.
Learning
There are times when it’s helpful to explain or educate users more. It’s important to Grafana Labs that users feel confident about their actions and Grafana Labs’ product capabilities.
Don’t just teach people how to perform an action, but also why they should.
Motivation
Motivate the user to continue by providing information about the next steps. Don’t assume the user knows what the next steps are or what the outcome will be.
