Word choice
Find the right term to use in your technical documentation. Apply this guidance as follows:
Preferred: This term is recommended.
Use with caution: This term might be ambiguous. Make sure you are using the term correctly.
Avoid: This term might be offensive or non-inclusive. Whenever possible, use the alternate suggestion, or a more specific term.
Tip
Use the Vale linter to check for style issues while writing documentation. Vale automatically flags common style guide violations, so you can catch and fix issues before publishing.
| Word | Status | Usage notes |
|---|---|---|
| abort | 🔴 Avoid | This word can be offensive. Use shut down, cancel, or stop instead. |
| above | 🟠Use with caution | Don't use to refer to a postion. Directional language does not meet accessibility requirements. |
| add | 🟢 Preferred | Use for establishing a new relationship. Often used in create-then-add scenarios: Create a dashboard, then add a visualization. Remove is the correct opposite. |
| app, application | 🟠Use with caution | Use only when needed for clarity. Otherwise, a Kibana app name can stand alone. App is a well-known abbreviation for application and is preferred. |
| begin | 🟠Use with caution | Similar to start, using begin depends on the context. Begin a procedure, begin an analysis, or begin an installation are common phrases. Similarly, start a program, start an engine, or start a timer are frequently used. Start is considered less formal than begin. End is the correct opposite of begin. |
| below | 🟠Use with caution | Don't use to refer to a position. Directional language does not meet accessibility requirements. |
| blacklist | 🔴 Avoid | This word has roots in racism. Use blocklist instead. |
| boot | 🔴 Avoid | Use start or run instead. |
| can | 🟢 Preferred | Use to convey permission. |
| cancel | 🟢 Preferred | Use to stop an action without saving pending changes. |
| cannot, can't | 🟢 Preferred | Use to indicate you don't have the ability to do something. Often confused with unable. |
| choose | 🔴 Avoid | Use select instead. |
| click | 🟠Use with caution | OK when describing mouse actions. Otherwise, use verbs that work with multiple devices, such as select. |
| clone | 🟠Use with caution | Use when creating a copy that is linked to the original. Often confused with copy and duplicate. |
| copy | 🟠Use with caution | Use when creating an exact copy in the same location as the original. Often confused with clone and duplicate. |
| could | 🔴 Avoid | Replace with can or might whenever possible. |
| create | 🟢 Preferred | Use for creating an object from scratch Not create new. Delete is the correct opposite. |
| delete | 🟢 Preferred | Use when deleting data that users can no longer retrieve. Create is the correct opposite. |
| disable | 🟠Use with caution | Don't use to describe something that is broken. Use inactive, unavailable, deactivate, turn off, or deselect, depending on the context. |
| duplicate | 🟠Use with caution | Use when creating a copy of an object in the same location as the original. Often confused with copy and clone. |
| easy, easily | 🔴 Avoid | It can be frustrating for users to think that something is easy, but then struggle to do the task. Typically the same meaning can be conveyed without this word. |
| edit | 🟢 Preferred | Not change or modify. Edit is the better choice for localization. |
| e.g. | 🔴 Avoid | Don't use Latin abbreviations. Use for example or such as instead. |
| enable | 🟢 Preferred | Use when turning on or activating an option or a feature. |
| enter | 🟢 Preferred | Use to refer to the user entering text. Not type. |
| execute | 🔴 Avoid | Use run or start instead. |
| hack | 🔴 Avoid | For a noun, use tip or work-around instead. For a verb, use configure or modify. |
| hit | 🔴 Avoid | For a noun, use visits (as in web visits). For a verb, use click or press. |
| i.e. | 🔴 Avoid | Don't use Latin abbreviations. |
| invalid | 🔴 Avoid | Use not valid or incorrect instead. |
| kill | 🟠Use with caution | Use cancel or stop unless the actual command is kill. |
| launch | 🔴 Avoid | Use open instead. |
| may | 🟠Use with caution | Use may for permissibility. Use can for capability. Use might for possibility. |
| open | 🟢 Preferred | Use instead of launch. |
| please | 🔴 Avoid | In most cases, please is unnecessary. Exceptions are situations where the user must wait or do something inconvenient. Or, if the text sounds too abrupt without it. |
| remove | 🟢 Preferred | Use when removing a relationship, but not permanently deleting the data. For example, you remove a visualization from a dashboard. Add is the correct opposite. |
| select | 🟢 Preferred | Select is preferred over choose. |
| simple, simply | 🔴 Avoid | Often used before a before a verb like select, but doesn't add any information or value. Implies that users should have been able to do such a simple task without assistance. |
| start | 🟠Use with caution | Start and begin depend on the context. Start a program, start an engine, or start a timer are common phrases. Similarly, begin a procedure, begin an analysis, or begin an installation are frequently used. Start is considered less formal than begin. |
| terminate | 🔴 Avoid | Use stop or exit instead. |
| type | 🔴 Avoid | Use enter because there is typically more than one way to enter text than typing. |
| unable | 🟠Use with caution | Unable means not being able to perform an action. Often confused with cannot. |
| utilize | 🟠Use with caution | Don't use utilize when you mean use. |
| view | 🟢 Preferred | Preferred over see because view is more inclusive. |
| whitelist | 🔴 Avoid | Use allowlist instead. |