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: StyleGuide.md
+18-18Lines changed: 18 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,16 +58,16 @@ In tutorials, where a conversational tone is sometimes helpful, use the second p
58
58
59
59
In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase.
60
60
61
-
-**Avoid:** Managing Users
62
-
**Avoid:** User Management
61
+
-**Avoid:** Managing Users
62
+
**Avoid:** User Management
63
63
**Prefer:** Manage Users
64
64
65
65
Do not use "we" to refer to "CockroachDB" or "Cockroach Labs".
66
66
67
-
-**Avoid:** We support changefeeds.
67
+
-**Avoid:** We support changefeeds.
68
68
**Prefer:** CockroachDB supports changefeeds.
69
69
70
-
-**Avoid:** We recommend ...
70
+
-**Avoid:** We recommend ...
71
71
**Prefer:** Cockroach Labs recommends ...
72
72
73
73
### Prescriptive writing
@@ -76,37 +76,37 @@ Write in a prescriptive style that clearly guides the user. The user should feel
76
76
77
77
Use active instead of passive voice.
78
78
79
-
-**Avoid:** Each parameter should be set explicitly.
79
+
-**Avoid:** Each parameter should be set explicitly.
80
80
**Prefer:** Set each parameter explicitly.
81
81
82
-
-**Avoid:** Additional options can be specified.
82
+
-**Avoid:** Additional options can be specified.
83
83
**Prefer:** You can specify additional options.
84
84
85
85
Use concise, direct language. Cut unnecessary words unless a conversational tone is intentional (for example, in tutorials). If a feature or concept is difficult to describe clearly or concisely, consider using an [example](#examples) or [image](#images) to complement the text.
86
86
87
-
-**Avoid:** Be mindful of the possibility that you might encounter a different result, depending on the specifics of your configuration, so you might want to do some testing first to see what happens.
87
+
-**Avoid:** Be mindful of the possibility that you might encounter a different result, depending on the specifics of your configuration, so you might want to do some testing first to see what happens.
88
88
**Prefer:** Run tests to verify that you get the expected result for your configuration.
89
89
90
-
-**Avoid:**`table_name`: This parameter is used to specify the name of the table you want to modify.
90
+
-**Avoid:**`table_name`: This parameter is used to specify the name of the table you want to modify.
91
91
**Prefer:**`table_name`: The name of the table to modify.
92
92
93
93
Provide guidance rather than leave decisions to the user. Avoid vague phrases like "as you wish" or "of your choice". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load.
94
94
95
-
-**Avoid:** Increase the threshold as needed.
95
+
-**Avoid:** Increase the threshold as needed.
96
96
**Prefer:** Increase the threshold until you see a performance improvement.
97
97
98
-
-**Avoid:** Define additional settings as desired.
98
+
-**Avoid:** Define additional settings as desired.
99
99
**Prefer:** You can define additional settings in the configuration file. To change the default host and port, set `host` and `port` respectively. To change the path, ...
100
100
101
-
-**Avoid:** Edit the profile using your preferred text editor.
101
+
-**Avoid:** Edit the profile using your preferred text editor.
102
102
**Prefer:** Edit the profile in a text editor.
103
103
104
104
Avoid vague time estimates. Provide a specific timeframe when possible.
105
105
106
-
-**Avoid:** You should set the grace period to at least a few minutes.
106
+
-**Avoid:** You should set the grace period to at least a few minutes.
107
107
**Prefer:** Set the grace period to at least 5 minutes.
108
108
109
-
-**Avoid:** This should take a few moments. When finished, click **Next**.
109
+
-**Avoid:** This should take a few moments. When finished, click **Next**.
110
110
**Prefer:** When finished, click **Next**.
111
111
112
112
Do not use contractions when giving a technical description or instruction.
@@ -118,29 +118,29 @@ Do not use "please" when giving an instruction, except when asking the user to g
118
118
119
119
-**Example:** If you need assistance, please contact [support](https://support.cockroachlabs.com/).
120
120
121
-
-**Avoid:** Please click on the **Next** button.
121
+
-**Avoid:** Please click on the **Next** button.
122
122
**Prefer:** Click **Next**.
123
123
124
124
Do not use language that could be read as presumptuous or condescending.
125
125
126
-
-**Avoid:** If you aren't willing to do this for some reason, ...
126
+
-**Avoid:** If you aren't willing to do this for some reason, ...
127
127
**Prefer:** If this is not possible, ...
128
128
129
-
-**Avoid:** Monitoring the cluster is simple.
129
+
-**Avoid:** Monitoring the cluster is simple.
130
130
**Prefer:** Monitor the cluster with the following tools:
131
131
132
132
### Speculation and feature support
133
133
134
134
Avoid forward-looking language when writing about supported syntax and behavior. Do not suggest that a feature may or may not be added in a future release. Avoid words like "yet" and "currently", and do not reference the internal product roadmap.
135
135
136
-
-**Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release.
136
+
-**Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release.
137
137
**Prefer:** CockroachDB does not support column-level privileges.
138
138
139
139
### Latinisms
140
140
141
141
For readability, avoid Latinisms.
142
142
143
-
-**Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
143
+
-**Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
144
144
**Prefer:** Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
0 commit comments