Skip to main content

Voice and Tone

It is essential to be aware of the following aspects of voice and tone:

  • When creating your documents, prioritize achieving a conversational, friendly, and respectful voice and tone while maintaining professionalism. Avoid excessive casualness or frivolity and seek a simple, approachable style that conveys a natural feel. Envision yourself as a knowledgeable friend who comprehends the needs and goals of the developer.

  • While we recommend embracing a conversational tone, it is crucial to strike a balance and avoid overly colloquial or verbose language, especially in developer documentation. Remember that the objective is to provide clear and concise information rather than imitating casual conversation.

  • Take into account that your readers may come from diverse cultural backgrounds and have varying English proficiency levels. Therefore, it is advisable to minimize using culturally specific references as much as possible. Moreover, employing simple and consistent writing can facilitate the translation of documents into other languages.

Tone vs voice​

"Tone" refers to the overall attitude or style of writing, while "voice" is the individual expression of the writer. Tone determines how the message is conveyed (formal, informal, persuasive), while voice is the writer's unique personality and style that comes through in writing.

Some voice styles to consider while writing Bucketeer content:

  • Conversational: A casual and friendly tone that mimics a conversation, creating a relatable and engaging atmosphere.

  • Empathetic: A compassionate and understanding tone that shows empathy towards the reader's experiences or challenges.

  • Instructional: A clear and step-by-step tone that provides practical guidance, instructions, or tutorials to help readers accomplish specific tasks or learn new skills.

Common mistakes​

In order to ensure a concise text flow and organization, please try to avoid:

  • Figures of speech, such as:

    • This software update is a game-changer.
    • Our team is racing against the clock to meet the deadline.

  • Long-winded sentences, avoid exceeding 25-30 words per sentence. For example:

    • During the iterative development cycle, continuous integration and continuous deployment practices are employed to ensure seamless integration of new features and enhancements into the existing codebase, thereby minimizing disruptions and maximizing productivity.

  • Starting all sentences with the same phrase (such as "You can" or "To do"). For example:

    • You can download the latest version of the software from our website.
    • You can collaborate with team members by sharing project files in real time.

  • Exclamation marks. Check some examples as follows:

    • The new update includes amazing features!
    • Introducing the revolutionary AI-powered assistant!

  • Internet slang or other internet abbreviations, such as:

    • BTW (by the way).
    • OMG (oh my God).
    • LOL (laugh out loud).

Using the word "please"​

Being polite is important, but be careful not to overuse the word "please":

❌   Not recommended👍   Recommended
To start the task, please click NextTo start the task, click Next