Tag: Documentation

Reading Time: 3 minutes

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:

1. 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:

1. Write the explanation
2. Add a simple example
3. Identify steps that might confuse users
4. Add screenshots only where needed
5. 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.