You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/onboarding-guide/voice-and-tone.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,21 @@
1
1
---
2
2
title: "Voice and Tone"
3
-
weight: 60
3
+
weight: 70
4
4
---
5
5
6
6
## Introduction
7
-
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.
7
+
Voice and tone are essential parts of writing effective documentation for AsyncAPI. How we write significantly impacts how our readers perceive and interact with our documentation. We communicate in a clear, instructive voice and a friendly tone to help readers understand complex technical concepts and feel confident in using the AsyncAPI specification.
8
8
9
9
10
10
## Our Voice
11
11
At AsyncAPI, we consider our voice to be:
12
12
13
-
- Clear and concise throughout the documentation. This way readers can get helpful information quickly even at a glance.
13
+
- Clear and concise throughout the documentation. This way, readers can get helpful information quickly, even at a glance.
14
14
15
15
**Example**
16
16
"A protocol is a set of rules that specifies how information is exchanged between applications and/or servers."
17
17
18
-
The above sentence uses clear and straightforward language to define what a protocol is in the context of the AsyncAPI specification.
18
+
The above sentence uses clear and straightforward language to define a protocol in the context of the AsyncAPI specification.
19
19
20
20
- An active voice to make the documentation more engaging and easier to understand.
21
21
@@ -37,7 +37,7 @@ While your voice remains constant, your tone may vary based on the audience's ne
37
37
</Remember>
38
38
At AsyncAPI, we consider our tone to be:
39
39
40
-
- Friendly and approachable that puts the reader at ease.
40
+
- Friendly and approachable, which puts the reader at ease.
41
41
42
42
- A helpful tone that addresses the reader's concerns or questions.
43
43
@@ -59,4 +59,4 @@ Here are a few key elements of writing AsyncAPI's voice:
59
59
60
60
- Use examples and code snippets to illustrate concepts and provide practical guidance.
61
61
62
-
- Use contractions to make the language more conversational e.g., "You've now added a new section called servers in your AsyncAPI document."
62
+
- Use contractions to make the language more conversational, e.g., "You've now added a new section called servers in your AsyncAPI document."
0 commit comments