Clear and Concise Writing
Clear, concise writing is essential for documentation. Users typically skim documentation under time pressure, searching for answers. Every word either helps or hinders their success.
Principles of Clear Writing
Principle 1: Use Simple, Familiar Words
Choose everyday words over complex or technical alternatives.
Complex: "Utilize this functionality to facilitate seamless integration" Clear: "Use this feature to integrate easily"
Complex: "The aforementioned parameters necessitate specification" Clear: "You must specify these parameters"
Principle 2: One Idea Per Sentence
Long, complicated sentences force readers to parse meaning. Short sentences are easier to scan and understand.
Complicated: "When you've completed the installation process and the system has finished configuring all necessary components, which typically takes several minutes depending on your network speed and computer specifications, you should see a confirmation message."
Clear: "Installation takes a few minutes. When it completes, you'll see a confirmation message."
Principle 3: Active Voice, Not Passive
Active voice is more direct and easier to understand.
Passive: "The installation can be performed by double-clicking the installer" Active: "Double-click the installer to install"
Passive: "It is recommended that changes be saved before closing" Active: "Save your changes before closing"
Principle 4: Be Specific, Not Vague
Vague language creates confusion. Use concrete details.
Vague: "Install the software and wait a bit" Specific: "Install the software. Wait for the confirmation message (usually 2-3 minutes)"
Vague: "Use appropriate authentication methods" Specific: "Use API keys or OAuth 2.0 tokens for authentication"
Reducing Unnecessary Words
Every word should serve a purpose. Remove redundancy and filler.
Common Unnecessary Phrases
| Wordy | Concise |
|---|---|
| "In order to" | "To" |
| "Due to the fact that" | "Because" |
| "In the event that" | "If" |
| "At the present time" | "Now" |
| "Take into consideration" | "Consider" |
| "For the purpose of" | "To" |
| "Make a decision" | "Decide" |
| "Repeat again" | "Repeat" |
| "Plan ahead in advance" | "Plan" |
Eliminating Redundancy
Redundant: "The complete list of all available options" Concise: "All available options"
Redundant: "First and foremost, you must initially..." Concise: "First, you must..."
Addressing the Reader
Speak directly to the reader using "you" to create engagement.
Impersonal: "The user must enter credentials" Direct: "Enter your credentials"
Impersonal: "It is necessary to configure settings" Direct: "You must configure these settings"
Impersonal: "One should backup regularly" Direct: "Back up your data regularly"
Tone and Voice
Documentation should sound professional but approachable—knowledgeable without being condescending.
Tone Characteristics
Confident: Show expertise; don't hedge with "might," "perhaps," "hopefully"
- "This will resolve the issue" (not "This might help")
- "Follow these steps" (not "You could try these steps")
Friendly: Use conversational language while remaining professional
- "Let's get started" (not "Commencing initialization procedures")
- "Here's what you need to know" (not "The following information is relevant")
Helpful: Focus on user success, not on showing off knowledge
- "We'll help you troubleshoot" (not "Advanced debugging techniques include...")
- "The simplest approach is..." (not "Naive implementations often employ...")
Avoid These Tones
Condescending: Avoid explaining obvious things or treating users as inexperienced Jargon-heavy: Avoid unnecessary technical jargon Overly Casual: Avoid slang or inappropriate informality Apologetic: Avoid unnecessary "sorry" or "unfortunately"
Paragraph and Section Conventions
Paragraph Structure
Keep paragraphs short for scannability:
- Lead with the main point
- 2-3 supporting sentences maximum
- One paragraph = one idea
Section Introductions
Begin each section with a clear purpose statement:
Good: "Before installing, you need a few things. This section covers system requirements, required software, and hardware specifications."
Poor: "There are some things you need to know about requirements."
Clarity Checklist
- Used simple, everyday words
- Kept sentences short (one idea per sentence)
- Used active voice
- Was specific with concrete details
- Removed redundant phrases
- Addressed reader directly ("you")
- Tone is confident, friendly, and helpful
- Paragraphs are short and focused
- Section introductions explain the purpose