Even experienced writers fall into recurring patterns that undermine documentation quality. The mistakes covered here are not obscure edge cases — they appear constantly in knowledge bases across every industry. Recognizing them in your own writing is the first step to eliminating them.
Most of these mistakes share a common cost that goes beyond reader frustration: a sentence weakened by hedging, marketing fluff, or ambiguity is also a sentence that a search engine, answer engine, or AI assistant cannot confidently extract or cite. Clear, direct, factual writing serves the human reader and the machine reader at the same time — voice quality and discoverability are not separate concerns.
Marketing Language in Documentation
Documentation and marketing have different jobs. Marketing persuades. Documentation informs. When marketing language bleeds into documentation, it erodes credibility and frustrates readers who are looking for factual information, not promotion. It also gives an AI system nothing concrete to cite — "the most powerful dashboard" is not a fact that can be extracted and repeated; "the dashboard shows page views and session duration" is.
Common marketing language to remove from documentation:
- Superlatives without evidence: "the most powerful," "the best," "industry-leading." These are claims, not information. Documentation does not make claims; it describes behavior.
- Excitement language: "amazing," "incredible," "game-changing," "innovative." These words add no information and signal that the writer is selling something.
- Feature promotion: "We are proud to offer..." or "Our powerful new feature lets you..." Documentation describes what a feature does, not how the organization feels about it.
| Marketing language (avoid) | Documentation language (prefer) |
|---|---|
| Our powerful analytics dashboard gives you incredible insights into your readers' behavior. | The analytics dashboard shows page views, session duration, search terms, and reader drop-off points. |
| We're excited to announce seamless integration with your favorite tools. | You can connect your knowledge base to external tools using the integrations panel in Settings. |
Hedging and Over-Qualification
Hedging — softening statements to the point where they provide no useful guidance — is one of the most common voice problems in documentation. It usually comes from a well-intentioned desire to avoid being wrong, but it leaves readers uncertain and frustrated.
| Hedged (avoid) | Direct (prefer) |
|---|---|
| You may want to consider reviewing your settings before proceeding. | Review your settings before proceeding. |
| It might be a good idea to save your work periodically. | Save your work periodically to avoid losing changes. |
| In some cases, this could potentially cause issues. | This can cause issues if [specific condition]. To prevent this, [specific action]. |
When genuine uncertainty exists — when a behavior truly varies by configuration or environment — say so directly: "This behavior varies depending on your permission level." That is honest specificity, not hedging.
Condescension: "Simply," "Just," "Easily," "Obviously"
These four words are among the most damaging in documentation. They signal that the writer considers the task trivial. When a reader who is struggling encounters them, the experience is demoralizing.
The words are rarely deliberate — writers use them reflexively. The fix is equally reflexive: develop a habit of finding and removing them in every draft.
| Condescending (avoid) | Neutral (prefer) |
|---|---|
| Simply click the button to save your changes. | Click Save. |
| Just navigate to your profile to update your details. | Go to your profile to update your details. |
| It's easy to export your data — just go to Settings. | To export your data, go to Settings. |
Inconsistent Terminology
Using different words for the same thing within a knowledge base is a subtle but significant problem. Readers who encounter "the dashboard," "the home screen," and "the main panel" across different articles reasonably wonder whether these refer to the same thing or three different things.
Pick one term for each concept and use it every time. Document your terminology decisions in the word usage section of your style guide so that all contributors use the same terms.
This applies to actions as well as nouns: if you call it "log in" in one article and "sign in" in another, readers notice. Consistency builds trust; inconsistency creates doubt.
Inconsistent Point of View
Distinct from terminology, point of view is how the writer addresses the reader — and switching between forms within the same article, or across the knowledge base, is a common and easy-to-miss mistake.
| Inconsistent (avoid) | Consistent (prefer) |
|---|---|
| Users can update their settings. Once you've made changes, we recommend saving them right away. | You can update your settings. Once you've made changes, save them right away. |
Pick one point of view — direct address ("you") is almost always the right choice for documentation — and use it throughout an article and across the knowledge base. Do not drift into third person ("the user," "users") or first-person-plural ("we recommend") mid-article.
Idioms and Culture-Bound Language
Phrases that rely on shared cultural or linguistic context — "hit the ground running," "ballpark figure," "out of the box" (used figuratively), "low-hanging fruit" — are easy to write without noticing, and hard for non-native speakers or machine translation to interpret correctly. They also rarely survive translation cleanly, which matters if your knowledge base is localized.
| Idiomatic (avoid) | Plain (prefer) |
|---|---|
| This feature works out of the box. | This feature works without additional setup. |
| You can get a ballpark figure from the estimate tool. | You can get an approximate figure from the estimate tool. |
| New team members should hit the ground running with this guide. | This guide helps new team members get started quickly. |
If a phrase would need to be explained to someone who learned English as a second language, replace it with a literal equivalent.
Passive Voice as a Default
Passive voice is not incorrect — it has legitimate uses. But when used habitually, it produces writing that is evasive, harder to read, and less engaging.
The specific problem with passive voice in documentation is that it obscures the actor — the person or system performing the action. Readers need to know who does what.
| Passive (avoid) | Active (prefer) |
|---|---|
| The form must be completed before access is granted. | Complete the form to gain access. |
| An error will be shown if the file cannot be found. | If the file cannot be found, an error message appears. |
| Settings can be accessed by navigating to the profile menu. | Go to the profile menu to access Settings. |
Punctuation Used for Emphasis
Exclamation points, scare quotes, and ALL CAPS are sometimes used to make a warning or a success message stand out. They tend to do the opposite: they read as unprofessional at best, and as false urgency at worst — a warning in all caps is not more likely to be read carefully than one written in a plain, well-placed sentence.
| Emphatic punctuation (avoid) | Plain, well-placed (prefer) |
|---|---|
| Your changes were saved!! | Your changes were saved. |
| WARNING: THIS CANNOT BE UNDONE | Warning: This action cannot be undone. |
| Make sure to "save" your work before leaving. | Save your work before leaving. |
If something genuinely needs to stand out, use a heading, a bold label, or a callout component — not punctuation.
Burying Warnings and Critical Information
A warning that appears after the step it warns about is useless. A critical piece of information buried in the fourth paragraph of an article may never be seen by a reader who scans. Warnings, prerequisites, and critical notices belong at the top — before the content they apply to.
This applies at the article level and at the step level. A warning inside a single step, written as a subordinate clause at the end of a long sentence, is just as easy to miss as one buried in a paragraph.
| Warning buried (avoid) | Warning upfront (prefer) |
|---|---|
| Follow steps 1 through 6 to complete the migration. Note: this process cannot be reversed once started. | Note: This process cannot be reversed once started. Follow steps 1 through 6 to complete the migration. |
| In step 4, delete the old configuration file, which is a permanent action you cannot undo, and then restart the service. | Step 4 is permanent and cannot be undone. Delete the old configuration file, then restart the service. |
Over-Long Introductions
Readers arrive at documentation with a task in mind. An article that takes three paragraphs to get to its first useful piece of information is an article many readers will abandon.
Documentation introductions serve one purpose: orienting the reader so they know they are in the right place. One to two sentences is almost always sufficient. If you find yourself writing more than that, ask whether the extra content belongs in the article at all — and if it does, whether it belongs at the beginning.
A good introduction tells the reader: here is what this article covers, and here is what you will be able to do after reading it. Everything else is delay.
Self-Audit Checklist
Before publishing, check every paragraph against these questions:
- Does every sentence make a factual claim or describe behavior — not an opinion or a promotional statement?
- Is every hedge honest uncertainty about something that genuinely varies, not timidity about a fact that's actually known?
- Have you removed "simply," "just," "easily," and "obviously"?
- Is the same term used for the same concept everywhere it appears?
- Is the point of view (you / we / the user) consistent throughout?
- Would a non-native English speaker understand every phrase literally?
- Is the sentence active, with a clear actor performing the action?
- Is emphasis carried by structure (headings, bold, callouts) rather than punctuation?
- Do warnings and prerequisites appear before the steps or content they apply to — at both the article level and the step level?
- Does the introduction get to useful information within one or two sentences?