Documentation

Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Kubernetes Kit and Azure Cloud Kit. Read the blog post.

Voice and Tone

Voice

By voice, we mean how we say what we need to say. When we write documentation, we have certain things that we need to communicate to our reader. But there are an infinite number of ways that we could express our message.

As people, we all develop ways of talking to others which say a lot about who we’re and how we see the world. In our documentation, we want to provide important information as clearly as possible. We would also like people to carry away a favorable impression of who we’re and what we stand for as a company.

Real, Helpful and Human

When we write documentation, we’re, at that moment, the public face of the company. If that sounds like a lot of responsibility, don’t worry. We all have it in us to be friendly and helpful – and that’s all that’s required. We need to remember to write like a real human being who cares about the reading audience.

Tone

As we have already said, voice is about conveying helpfulness and professionalism by how we approach explaining things. But while we’re explaining, we also need to adopt an appropriate tone.

Tone is more about finding the correct balance between being stiff and formal, and being overly relaxed and flippant. We can take great care to explain issues thoroughly and thoughtfully. But if we use language that’s so formal that it sounds unfriendly, or so informal that it sounds unreliable, we risk wasting all the effort that we put into our explanations.

The tone that we’re aiming for is friendly. We want to sound professional, but not overly formal.

Humor

It’s acceptable to use a little humor from time to time. Don’t overdo it, however, as it can distract from the message that we’re trying to communicate. Additionally, sense of humor is particularly dependent on a person’s cultural background. What’s funny to us may not be so amusing to someone from a different culture; it may even be offensive.

CE4D836F-1A6A-4096-9CE5-E59BE5542CF7