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: contribute-docs/style-guide/accessibility.md
+10-11Lines changed: 10 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -190,33 +190,32 @@ Different people are used to different names, currencies, date and time formats,
190
190
* Avoid ambiguous values, like `04/05/06` for a date. Is it May 4 or April 5, and which year? `11/17/1987` leaves less room for interpretation if the exact format is not specified nearby.
191
191
* If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience.
192
192
193
-
✔️ **Avoid idioms or expressions that are not commonly known, also known as regionalisms.**
193
+
✔️ **Avoid idioms or expressions that are not commonly known, also known as regionalisms.**
194
194
195
-
In our Elastic documentation, we aim for a fun, friendly, and sometimes quirky
196
-
tone. To achieve that, it can help to use informal, playful language. However,
197
-
we also have to be careful that our text is as inclusive as possible, so we try
198
-
to avoid expressions that might be unknown or opaque to some readers. Here are
199
-
a few examples of what to avoid:
195
+
In our Elastic documentation, we aim for a fun, friendly, and sometimes quirky tone.
196
+
To achieve that, it can help to use informal, playful language.
197
+
However, we also have to be careful that our text is as inclusive as possible, so we try to avoid expressions that might be unknown or opaque to some readers.
198
+
Here are a few examples of what to avoid:
200
199
201
200
* Idioms (for example, _It's a piece of cake_ or _So far so good_)
202
201
* Regional expressions (for example, _G'day!_, _Y'all_, or _eh_)
203
202
* Sports expressions (for example, _touched base_ or _threw a curve ball_)
204
203
* Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_)
205
204
206
-
We're all pretty good at avoiding these, but there's one problematic type of
207
-
expression that shows up frequently in docs reviews. Latin terms and
208
-
abbreviations are a common source of confusion, particularly for people whose
209
-
first language does not have Latin roots.
205
+
We're all pretty good at avoiding these, but there's one problematic type of expression that shows up frequently in docs reviews.
206
+
Latin terms and abbreviations are a common source of confusion, particularly for people whose first language does not have Latin roots.
210
207
211
208
Here are some terms to avoid and suggested alternatives:
212
209
213
210
| Avoid | Use instead |
214
211
| ----- | ----------- |
215
-
| e.g. (exempli gratia) | For example |
212
+
| e.g. (exempli gratia) | For example |
216
213
| etc. (et cetera) | And more, and so on |
217
214
| i.e. (id est) | That is |
218
215
| via | By way of, by means of, through |
219
216
217
+
For more examples, refer to [](/contribute-docs/style-guide/word-choice.md)
218
+
220
219
✔️ **Aim for readability.** Tools like the Hemingway App can help you make content simpler. Be conversational, but prioritize clarity.
Copy file name to clipboardExpand all lines: contribute-docs/style-guide/seo.md
+2-6Lines changed: 2 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -191,7 +191,7 @@ Best practices:
191
191
192
192
* Use structured data (for example, [schema.org](https://schema.org/) markup) to add semantic meaning.
193
193
Structured data can help search engines display your documentation in rich results, such as FAQs or How-To snippets.
194
-
Check with the documentation team for existing capabilities or implementation guidance.
194
+
Check with the documentation team for existing capabilities or implementation guidance. If you're an external contributor, open a GitHub issue to discuss implementation options.
195
195
196
196
### Content length
197
197
@@ -253,7 +253,6 @@ Best practices:
253
253
254
254
* Accessibility considerations
255
255
256
-
* Use semantic HTML (`<ul>`, `<ol>`, `<li>`) for lists.
257
256
* Avoid using lists for layout or decorative purposes.
258
257
259
258
### Interlinking
@@ -277,7 +276,6 @@ Best practices:
277
276
* Use external links judiciously
278
277
279
278
* Link to reputable, authoritative sources when necessary. For example, `https://www.python.org/doc/`.
280
-
* Ensure external links open in a new tab/window.
281
279
282
280
* Maintain link accessibility
283
281
@@ -351,9 +349,7 @@ Best practices:
351
349
* Avoid unnecessary words or parameters.
352
350
* Use hyphens (-) to separate words for clarity.
353
351
354
-
* Use lowercase letters
355
-
356
-
* Always use lowercase to prevent duplicate content issues (e.g., /Guide/ vs. /guide/).
352
+
* Always use lowercase to prevent duplicate content issues.
0 commit comments