Skip to content

Commit 9e28de3

Browse files
committed
More minor edits
1 parent b8f5d4e commit 9e28de3

File tree

3 files changed

+14
-17
lines changed

3 files changed

+14
-17
lines changed

contribute-docs/style-guide/accessibility.md

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -190,33 +190,32 @@ Different people are used to different names, currencies, date and time formats,
190190
* 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.
191191
* If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience.
192192

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.**
194194

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:
200199

201200
* Idioms (for example, _It's a piece of cake_ or _So far so good_)
202201
* Regional expressions (for example, _G'day!_, _Y'all_, or _eh_)
203202
* Sports expressions (for example, _touched base_ or _threw a curve ball_)
204203
* Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_)
205204

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.
210207

211208
Here are some terms to avoid and suggested alternatives:
212209

213210
| Avoid | Use instead |
214211
| ----- | ----------- |
215-
| e.g. (exempli gratia) | For example |
212+
| e.g. (exempli gratia) | For example |
216213
| etc. (et cetera) | And more, and so on |
217214
| i.e. (id est) | That is |
218215
| via | By way of, by means of, through |
219216

217+
For more examples, refer to [](/contribute-docs/style-guide/word-choice.md)
218+
220219
✔️ **Aim for readability.** Tools like the Hemingway App can help you make content simpler. Be conversational, but prioritize clarity.
221220

222221
#### Use gender-neutral language

contribute-docs/style-guide/grammar-spelling.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,8 @@ Avoid Latin abbreviations for common English phrases, unless space is limited.
431431
✔️ **Do**: for example
432432
:::
433433

434+
For more examples, refer to [](/contribute-docs/style-guide/word-choice.md)
435+
434436
## Glossary
435437

436438
For a list of terms and abbreviations commonly used in our docs, refer to the [Glossary](/reference/glossary/index.md).

contribute-docs/style-guide/seo.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ Best practices:
191191

192192
* Use structured data (for example, [schema.org](https://schema.org/) markup) to add semantic meaning.
193193
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.
195195

196196
### Content length
197197

@@ -253,7 +253,6 @@ Best practices:
253253

254254
* Accessibility considerations
255255

256-
* Use semantic HTML (`<ul>`, `<ol>`, `<li>`) for lists.
257256
* Avoid using lists for layout or decorative purposes.
258257

259258
### Interlinking
@@ -277,7 +276,6 @@ Best practices:
277276
* Use external links judiciously
278277

279278
* Link to reputable, authoritative sources when necessary. For example, `https://www.python.org/doc/`.
280-
* Ensure external links open in a new tab/window.
281279

282280
* Maintain link accessibility
283281

@@ -351,9 +349,7 @@ Best practices:
351349
* Avoid unnecessary words or parameters.
352350
* Use hyphens (-) to separate words for clarity.
353351

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.
357353

358354
* Avoid special characters
359355

0 commit comments

Comments
 (0)