This article lists words and phrases that consistently produce weak, vague, condescending, or misleading documentation. For each entry, the reason it is problematic is explained, and a better alternative is provided.
This is not a list of grammatically incorrect words — it is a list of words that work against the reader. Some are individually harmless but become corrosive as a habit. Others signal a specific type of problem in the writing.
How this relates to the Voice and Tone guide: the Common Voice and Tone Mistakes guide covers the same underlying categories — condescension, marketing language, hedging, filler — in depth, with the reasoning behind each rule and a broader self-audit checklist. This article is the fast, flat, scan-during-editing companion to that one: use this list for a quick pass over a draft, and use the Voice and Tone guide when you want the fuller explanation of why a category of language causes problems.
Words That Condescend
| Avoid | Why | Use instead |
|---|---|---|
| simply | Implies the task is easy. Makes struggling readers feel inadequate. | Remove it. The step is no less clear without it. |
| just | Same problem as "simply." Also often used to minimize something that is actually significant: "just contact support." | Remove it. "Click Save" needs no modifier. |
| easily | A judgment call about difficulty that readers may not share. | Remove it or replace with a factual statement about what makes it straightforward, if relevant. |
| obviously | Anything truly obvious does not need to be documented. Calling something obvious is at best redundant, at worst insulting. | Remove it. State the information without the editorial comment. |
| of course | Implies the reader should already know this. | Remove it. |
| feel free to | Adds no information. Readers do not need permission to use features you are documenting. | Remove it. "Contact support" not "feel free to contact support." |
Words That Inflate
| Avoid | Why | Use instead |
|---|---|---|
| powerful | Marketing adjective. Describes no specific capability. | Describe what the feature does. "The analytics dashboard tracks page views, session duration, and reader exit points." |
| robust | Another marketing adjective that says nothing specific. | Be specific about capabilities or scope. |
| seamlessly | A claim without evidence. Integration that requires configuration and testing is not seamless. | Describe how the integration works. Remove the adjective. |
| innovative / cutting-edge / state-of-the-art | Dates quickly. Not something documentation writers can claim without evidence. | Describe what the feature does, not how impressive it is. |
| leverage | Corporate jargon for "use." | Use "use." |
| utilize | A longer, more formal word for "use" with no additional precision. | Use "use." |
Words That Hedge
| Avoid | Why | Use instead |
|---|---|---|
| you may want to | Vague. Is this a recommendation or not? | Either recommend it directly ("Back up your data before proceeding") or explain the condition ("If you have unsaved changes, back up your data first"). |
| it is possible to | Weak framing. Everything in documentation is "possible" — that is why it is documented. | "You can..." or just describe the action. |
| in some cases | Too vague to be useful. Which cases? The reader needs to know whether this applies to them. | Specify the condition: "If your account is on a Business plan..." or "If you have multiple workspaces..." |
| generally / typically / usually | These qualifiers are sometimes necessary, but they are often used as hedges when a direct statement is more accurate. | Use them only when genuine variation exists and you cannot be more specific. If the behavior is consistent, state it directly. |
Filler Phrases
| Avoid | Why | Use instead |
|---|---|---|
| Please note that | Adds no information. "Note:" does the same job in one word. | "Note:" or restructure the sentence without the filler. |
| It is important to note that | Same problem as above, with more words. | State the important information directly. |
| In order to | Longer version of "to." | "To" |
| At this point in time | Longer version of "now." | "Now" or "currently" |
| Due to the fact that | Longer version of "because." | "Because" |
| In the event that | Longer version of "if." | "If" |
| For the purposes of | Adds length without adding meaning. | Rewrite the sentence without it. |
Words That Can Cause Accessibility and Localization Problems
| Avoid | Why | Use instead |
|---|---|---|
| above / below (when referring to content position) | Position-based references break when content is reordered or viewed in a different format. Screen readers do not convey "above" meaningfully. | Use links or section names: "as described in the Prerequisites section" or "see Formatting and structure." |
| click here | Provides no information about where the link leads. Screen readers announce links without surrounding context. See the Links section of the Formatting Standards guide for the full link-text rule. | Descriptive link text: "see the formatting guidelines" or "download the CSV template." |
| see above / see below | Same problem as above/below positional references. | Use the section or article name: "see Callout types." |
Words to Avoid for Inclusive Language
| Avoid | Why | Use instead |
|---|---|---|
| blacklist / whitelist | Terminology with negative racial connotations. Being replaced across the industry. | blocklist / allowlist |
| master / slave (in technical contexts) | Same concern. Being replaced across technical documentation. | primary / replica, leader / follower, source / target (depending on context) |
| generic "he" as a default pronoun | Assumes a gendered default for a reader whose gender is unknown and irrelevant to the content. | Use "they," or address the reader directly as "you" — see the Point of View section of the Voice and Tone guide. |
This list is not exhaustive, and inclusive-language conventions continue to evolve. If you encounter a term you're unsure about, check current industry guidance rather than assuming the absence of a term here means it's fine to use.
Using This List
- Run a search-and-scan pass over a draft using this list before publishing, in addition to (not instead of) the fuller Voice and Tone review.
- Treat the inclusive-language section as a starting point, not a complete inventory — verify uncertain terms against current guidance.
- When in doubt about whether a flagged word is being used as intended, check the "why" column — if the underlying problem doesn't apply in a specific sentence, use judgment rather than removing the word reflexively.