-
Notifications
You must be signed in to change notification settings - Fork 0
/
tone_and_content.yml
67 lines (55 loc) · 2.89 KB
/
tone_and_content.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
description: Guidelines about what to say and how to say it.
content:
- section: Aperture Science products
sectionrules:
- rule: |
### Latency and uptime<br>
Don't make specific promises about latency, uptime, or related topics in public-facing documentation. These details should be reserved for SLAs and contracts.
audience: [tw, dev]
- rule: |
### Unrealistic claims<br>
Don't make unsubstantiated or unrealistic claims about Aperture Science, including who we are, what we do, the services we offer, or how our products work.
audience: [tw, dev, mktg]
- rule: |
### Unreleased products<br>
Don't mention unreleased products or features in public-facing documentation.
audience: [tw, dev]
- section: Tone
sectionrules:
- rule: |
### Be friendly<br>
Strive for an approachable, friendly tone—polished, professional, but not excessively formal.
audience: [tw, dev, mktg]
featured: |
[Strive for an approachable, friendly tone.]({{site.baseurl}}{{page.permalink}}tone-and-content/#be-friendly)
- rule: |
### Write for non-experts<br>
Write in a way that's easy for most people to understand, even if the reader isn't an expert in a given topic. A good rule of thumb: estimate the expertise of your average reader, then write for an audience with slightly less expertise than that.
audience: [tw, dev, mktg]
featured: |
[Write for a broad audience, not just for experts.]({{site.baseurl}}{{page.permalink}}tone-and-content/#write-for-non-experts)
- section: Word choice
sectionrules:
- rule: |
### Filler words<br>
Avoid filler words like *very.* Rather than describing a task as *very important*, you might say that it's *critical*.
audience: [tw, dev, mktg]
featured: |
[Avoid filler words.]({{site.baseurl}}{{page.permalink}}tone-and-content/#filler-words)
- rule: |
### Simple vs. complex<br>
When possible, try to use short, simple words instead of complex, abstract words.
examples:
- |
**Weak:** This setting facilitates data filtering.
- |
**Strong:** This setting lets you filter data.
audience: [tw, dev, mktg]
featured: |
[Try to use short, simple words instead of complex, abstract words.]({{site.baseurl}}{{page.permalink}}tone-and-content/#simple-vs.-complex)
- rule: |
However, if there's no way to avoid using complicated words or technical jargon, it's often helpful to give a definition, include [a hyperlink]({{site.baseurl}}{{page.permalink}}formatting-and-organization/#links) to related materials, or provide other additional context.
examples:
- |
**Example:** Be careful not to cross the black hole's event horizon. An event horizon is the point at which an object's gravity becomes too strong to escape—if you cross the event horizon, you'll never come back.
audience: [tw, dev, mktg]