One of the fastest ways to improve your documentation is simple:
Show more. Tell less.
Examples and screenshots bridge the gap between explanation and understanding. They take something abstract and make it concrete.
Used poorly, they can clutter your content, confuse readers, or even make things harder to follow. Used correctly, they provide clarity.
This guide will show you how to use examples and screenshots the right way.
Why Examples and Screenshots Matter
People don’t learn well from explanations alone.
They learn when they can:
- See what something looks like
- Understand how it behaves
- Recognize patterns
Examples and screenshots:
- Reduce confusion
- Speed up learning
- Increase confidence
If your goal is clarity, they’re not optional; they’re essential.
When to Use Examples
Use examples anytime you’re explaining something that could be misunderstood.
1. When Explaining Concepts
Abstract ideas need concrete examples.
Without example:
A variable stores a value.
With example:
A variable stores a value. For example:
name = "John"
The second version is instantly clearer.
2. When Showing Input and Output
Users need to see both what goes in and what comes out.
Example:
Input:
HelloOutput:
HELLO
This removes guesswork.
3. When Demonstrating Patterns
Examples help users recognize structure.
Example:
email = "user@example.com"
username = "user123"
Now the reader sees how values are typically formatted.
4. When Clarifying Edge Cases
Examples can show what not to do.
Example:
Correct:
user_name
Incorrect:user name(spaces are not allowed)
This prevents common mistakes.
How to Write Good Examples
Not all examples are helpful. Here’s how to make yours effective.
Keep Them Simple
Don’t overload examples with unnecessary detail.
Bad:
userAccountName = "JohnDoe1987_admin_user_primary"
Better:
username = "johndoe"
Focus on clarity, not realism.
Make Them Relevant
Use examples that match the reader’s situation.
If you’re writing for beginners, avoid complex scenarios. If you’re writing for developers, use realistic data.
Label Them Clearly
Tell the reader what they’re looking at.
Example:
Command:
npm install
Result:
Packages installed successfully
Don’t make users guess.
Place Them Immediately After the Explanation
Don’t separate examples from the concept they explain.
Bad structure:
- Explanation (top of page)
- Example (far below)
Good structure:
- Explanation
- Example (immediately after)
Keep them connected.
When to Use Screenshots
Screenshots are most useful when text alone isn’t enough.
1. When the Interface Matters
If users need to click something specific, show it.
Example:
- Complex menus
- Multiple buttons
- Unfamiliar layouts
A screenshot can prevent wrong clicks and frustration.
2. When There’s Visual Feedback
Show what success looks like.
- Confirmation messages
- Error messages
- Completed forms
This helps users verify they’re on the right track.
3. When Steps Are Hard to Describe
Some actions are easier to show than explain.
If your instructions feel long or awkward, a screenshot might simplify everything.
How to Use Screenshots Effectively
Screenshots should clarify the instructions, not overwhelm the reader.
Keep Them Focused
Crop out unnecessary parts of the screen.
Highlight what matters:
- Buttons
- Fields
- Menus
If everything is visible, nothing stands out.
Add Annotations
Use arrows, boxes, or highlights to guide attention.
Don’t assume users will “just see it.”
Match the Step Exactly
Each screenshot should correspond to a specific step.
Example:
- Click Settings
Avoid generic screenshots that don’t match the action.
Example Steps
In the screenshot below, I’ve used an arrow and numbered steps to highlight the location of specific settings for the WS Form plugin. The numbers correspond to the steps in the instructions. See the article How to Control WordPress Blocks with PersonalizeWP for context.
Keep Them Updated
Outdated screenshots are worse than no screenshots.
If the interface changes:
- Update images
- Or remove them
Nothing confuses users faster than mismatched visuals.
When NOT to Use Screenshots
More screenshots do not equal better documentation.
Avoid screenshots when:
- The step is simple (“Click OK”)
- The interface is obvious
- The image adds no new information
If the screenshot doesn’t help, remove it.
A Simple Rule to Follow
Before adding an example or screenshot, ask:
Does this make the content easier to understand or follow?
If yes, include it.
If not, leave it out.
A Practical Workflow
Here’s a simple process you can use:
- Write the explanation
- Add a simple example
- Identify steps that might confuse users
- Add screenshots only where needed
- Review for clarity and remove anything unnecessary
Common Mistakes to Avoid
- Overloading examples with too much detail
- Using irrelevant or unrealistic examples
- Adding too many screenshots
- Using blurry or cluttered images
- Letting screenshots become outdated
Final Thoughts
Examples and screenshots are tools, not decorations.
Used well, they make your documentation clear, practical, and easy to follow.
Used poorly, they create noise.
The goal isn’t to show everything.
It’s to show just enough to help the user succeed.
