Skip to content

Commit ff15278

Browse files
committed
fix Avoid/Prefer line break
1 parent dde17c0 commit ff15278

File tree

1 file changed

+18
-18
lines changed

1 file changed

+18
-18
lines changed

StyleGuide.md

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,16 +58,16 @@ In tutorials, where a conversational tone is sometimes helpful, use the second p
5858

5959
In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase.
6060

61-
- **Avoid:** Managing Users
62-
**Avoid:** User Management
61+
- **Avoid:** Managing Users
62+
**Avoid:** User Management
6363
**Prefer:** Manage Users
6464

6565
Do not use "we" to refer to "CockroachDB" or "Cockroach Labs".
6666

67-
- **Avoid:** We support changefeeds.
67+
- **Avoid:** We support changefeeds.
6868
**Prefer:** CockroachDB supports changefeeds.
6969

70-
- **Avoid:** We recommend ...
70+
- **Avoid:** We recommend ...
7171
**Prefer:** Cockroach Labs recommends ...
7272

7373
### Prescriptive writing
@@ -76,37 +76,37 @@ Write in a prescriptive style that clearly guides the user. The user should feel
7676

7777
Use active instead of passive voice.
7878

79-
- **Avoid:** Each parameter should be set explicitly.
79+
- **Avoid:** Each parameter should be set explicitly.
8080
**Prefer:** Set each parameter explicitly.
8181

82-
- **Avoid:** Additional options can be specified.
82+
- **Avoid:** Additional options can be specified.
8383
**Prefer:** You can specify additional options.
8484

8585
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.
8686

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.
8888
**Prefer:** Run tests to verify that you get the expected result for your configuration.
8989

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.
9191
**Prefer:** `table_name`: The name of the table to modify.
9292

9393
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.
9494

95-
- **Avoid:** Increase the threshold as needed.
95+
- **Avoid:** Increase the threshold as needed.
9696
**Prefer:** Increase the threshold until you see a performance improvement.
9797

98-
- **Avoid:** Define additional settings as desired.
98+
- **Avoid:** Define additional settings as desired.
9999
**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, ...
100100

101-
- **Avoid:** Edit the profile using your preferred text editor.
101+
- **Avoid:** Edit the profile using your preferred text editor.
102102
**Prefer:** Edit the profile in a text editor.
103103

104104
Avoid vague time estimates. Provide a specific timeframe when possible.
105105

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.
107107
**Prefer:** Set the grace period to at least 5 minutes.
108108

109-
- **Avoid:** This should take a few moments. When finished, click **Next**.
109+
- **Avoid:** This should take a few moments. When finished, click **Next**.
110110
**Prefer:** When finished, click **Next**.
111111

112112
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
118118

119119
- **Example:** If you need assistance, please contact [support](https://support.cockroachlabs.com/).
120120

121-
- **Avoid:** Please click on the **Next** button.
121+
- **Avoid:** Please click on the **Next** button.
122122
**Prefer:** Click **Next**.
123123

124124
Do not use language that could be read as presumptuous or condescending.
125125

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, ...
127127
**Prefer:** If this is not possible, ...
128128

129-
- **Avoid:** Monitoring the cluster is simple.
129+
- **Avoid:** Monitoring the cluster is simple.
130130
**Prefer:** Monitor the cluster with the following tools:
131131

132132
### Speculation and feature support
133133

134134
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.
135135

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.
137137
**Prefer:** CockroachDB does not support column-level privileges.
138138

139139
### Latinisms
140140

141141
For readability, avoid Latinisms.
142142

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 }}.
144144
**Prefer:** Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
145145

146146
## Word usage guidelines

0 commit comments

Comments
 (0)