How to Engage Readers: Optimizing Image Use in Documentation

Most people are visual learners. Images in docs help people understand your product more easily. It is odd to publish your docs without any images. A huge wall of text is the last thing a user wants to see. Remember, YouTube is just a click away!

Having too many images though? Yeah, that will frustrate your readers sooner than you imagine. Not only that, multiple images make your page load slower, annoying your readers even more. So, what’s the solution?

I firmly believe that the “one image for every 150-300 words”, wouldn’t make sense for technical documentation. The number of images varies heavily based on the type of product and documentation.

For instance, a “getting started” guide to help people start using your product will need many images. Users expect to see different parts of the product so they can understand it better.

This article will help you answer these questions and reduce images in your docs without sacrificing product knowledge.

Removing Obvious Images from your Docs

We usually try to write documentation that can be easily understood by everyone, especially beginners who are new to the product.

While this is great, the last thing we want to do is to make them feel stupid. Extensive spoon-feeding will bother your readers and might even drive them away.

For instance, the following image just seems useless as the user is smart enough to figure this out on their own.

• Click on the “Cancel” icon to quit the editor.

Most users know this. Instead, say something like “Quit the editor after saving your changes”.

Some other examples:

• System alerts or notifications that don't require visual representation to understand, such as "You have successfully updated your profile”.

• Navigation steps like "Click on the home button to return to the homepage”.

• Default settings or configurations that don't require modification or explanation.

Replace Images with Text

Recognize when certain images are not needed. For example:

• Search for the “Python” extension here.

• Click on the “Install” button once you find it.

Instead, you can use text to combine both these images.

• Search and install the “Python” extension from your editor.

For longer texts, you can break the information down into bullet points. For example:

• Search for the “Python” extension within the Extensions tab.

• Click on the “Install” button.

Prioritize Relevant Content

Only include images that directly support the main points or arguments of the article. Eliminate any decorative images.

Brand logos and featured images may not fit the style of documentation. These kinds of visuals are more suitable for content blogs. If possible, cut them out from your docs. If necessary, include these as thumbnails instead of adding them directly within your technical article.

Hyperlink Whenever Possible

Hyperlinking is a great way to reduce information overload. While hyperlinks are used for minimizing textual information, you can also use it to reduce the images in your docs. For example:

• Open files in each editor are displayed with tabbed headers (Tabs) at the left of the editor.

Instead, you can simply hyperlink this:

Open files in each editor are displayed with tabbed headers (Tabs) at the top of the editor region. To learn more about tabbed headers, see the Tabs section.

Use Multiple Annotations

Instead of adding multiple images to show different parts of the same screen, consider using annotations. These can be arrows, highlights, and rectangles that’ll help you break the image down into multiple components.

For example, here’s an image showing different parts of Visual Studio Code:

You can explain what each section does below this image. This saves us time as well, since we don’t need to dedicate a separate image to each section.

Use AI to Your Advantage

LLM’s like ChatGPT, and Gemini are great at providing image feedback. Unfortunately, if you’re a free user like myself, ChatGPT won’t help much. This is because it only lets you upload images on the paid version.

Gemini will allow you to upload images on their free version, but you would have to upload and arrange it one by one within the docs. Copy-pasting images sadly isn't possible in Gemini.

Here’s what I do:

• Paste my entire technical article on ChatGPT/Gemini

• Provide descriptive alt texts to images within the preferred LLM

• Enter this prompt: Recognize unnecessary images within the following document without sacrificing on any product knowledge. Also, don’t remove any main keywords or important information.

This is what I mostly use. Most suggestions provided are garbage but a few of them are genuinely insightful.

Of course, if you have enough time, you can use Gemini to upload images one by one. I’ve never tried it myself, due to it being so tedious.

Review your Draft Multiple Times

I usually review my article 3-4 times before publishing it. You wouldn’t imagine the amount of content I remove upon second glance.

There were times when I had to cut off nearly 50% of the content written in the first draft. This includes images that could’ve been easily removed or replaced by text.

The power of reviewing your draft is remarkable. It’s even better if you have a separate set of eyes to review it before you publish. This ensures impartiality, as you may have become biased after spending extensive time capturing and editing a specific image.

Conclusion

That’s basically it. This is the checklist I follow before publishing my articles. I mainly wrote this article for myself as a checklist to follow but then decided to expand upon it and publish it.

If you guys have any thoughts, suggestions, or criticisms on this, please leave a comment. I would love to improve upon it!