diff --git a/docs/onboarding-guide/voice-and-tone.md b/docs/onboarding-guide/voice-and-tone.md new file mode 100644 index 000000000..53bc5cdaa --- /dev/null +++ b/docs/onboarding-guide/voice-and-tone.md @@ -0,0 +1,62 @@ +--- +title: "Voice and Tone" +weight: 60 +--- + +## Introduction +Voice and tone are essential parts of writing effective documentation for AsyncAPI. The way we write significantly impacts how our readers perceive and interact with our documentation. To help readers understand complex technical concepts and feel confident in using the AsyncAPI specification, we communicate in a clear, instructive voice and a friendly tone. + + +## Our Voice +At AsyncAPI, we consider our voice to be: + +- Clear and concise throughout the documentation. This way readers can get helpful information quickly even at a glance. + +**Example** +"A protocol is a set of rules that specifies how information is exchanged between applications and/or servers." + +The above sentence uses clear and straightforward language to define what a protocol is in the context of the AsyncAPI specification. + +- An active voice to make the documentation more engaging and easier to understand. + +**Example** +"The Generator receives Template and params as input." (active) +"The input of Template and params is received by the Generator."(passive) +From the above example sentences, the active voice is easier to understand than the passive. + +- Inclusive in terms of language, meaning welcoming to all readers and avoidance of internet slang such as YMMV (your method may vary), IMO (in my opinion), etc. + +- A voice that is accessible to both technical and non-technical audiences. + + +## Our Tone + + +While your voice remains constant, your tone may vary based on the audience's needs in certain contexts. + + +At AsyncAPI, we consider our tone to be: + +- Friendly and approachable that puts the reader at ease. + +- A helpful tone that addresses the reader's concerns or questions. + +- An authoritative tone that establishes trust in the documentation and its authors. + +- A consistent tone throughout the documentation to maintain coherence. + + +## Style Tips +Here are a few key elements of writing AsyncAPI's voice: + +- Use "you" to address the reader directly, e.g., "You will be using the Eclipse Mosquitto broker." + +- Use "we" to refer to the documentation authors, e.g., "We recommend using the latest version of the AsyncAPI specification." + +- Use short sentences and paragraphs to make the documentation easier to read and digest. + +- Use headings, subheadings with proper hierarchy, and bullet points to break up texts and make them more scannable. + +- Use examples and code snippets to illustrate concepts and provide practical guidance. + +- Use contractions to make the language more conversational e.g., "You've now added a new section called servers in your AsyncAPI document." \ No newline at end of file