How I decided not to use images in technical documents

Recently, I started to question how useful images are in technical writing. There is a benefit, obviously, in using images — whether they are screenshots, diagrams, etc. There are cons too in using these images. I reconsidered the idea of using images and, eventually, decided not to use them all.

This article tells my experience and how I decided not to use images in my technical documents.

Before having full responsibility for the technical documentation in Netsparker, I was working with two other writers. So, we were three people writing and updating the documentation…and adding images to our documents :)

Then, the day came when I found myself alone in keeping up with all that responsibility. While writing and updating documents were not enough, I have been pushing myself to write blog posts about the product. I also attend bi-weekly scrum meetings to track upcoming changes closely that helps me to write and/or update the documents accordingly.

So, when I found myself alone, I decided to spend my time and energy on useful matters that are, I believe, critical to users. I understood that most of the time, the procedure were there and could have minor changes. These changes are something that I can keep up with and update the documentation. These minor changes can be like requiring users to enter an API token instead of a password for the issue tracking integration or adding another functionality for CI/CD pipeline.

While these changes require less time and energy for updating the document, I cannot say the same thing for the images. You have to keep track of all visual changes in your application. As a lone writer, that may not be possible. It is time-consuming and challenging.

Even you have labor force, visuals pose another challenge: Where to store them and put them in your documents. Do you plan to put all screenshots in the documents or plan to be selective? If you decided to put all these visuals, users may find it difficult to follow your documents. If you decided to be selective, how you are going to decide which one you use.

Another challenge is the agile methodology. Because of this approach, there have been incremental changes all the time. All these windows, visuals, screens, etc. may change within a week. Or, the last-minute changes in the feature that may require you to update all these screenshots you took with care.

So, I decided not to use no visuals at all. If I use, I keep them very minimum — one or two.

When I decided not to use any images, I found myself in a better position. I focused on improving how I tell the story rather than painstakingly dealing with all these images. Let’s image there is a minor change in the product. It does not require so many hours to update the document. You can also update easily other documents that are affected by that minor change. What if there is a major change or new functionality? As I use no images or keep the usage at a minimum -like one screenshot-, I can write my document effortlessly.

This approach also let me publish some documents that my former co-workers had written. While they are leaving the company, they told me to find the images and then publish the documents. I tried and contacted developers to get these images but no to avail… Developers can be very busy, you know :) When I dropped the visual requirements, I published these documents that stayed there for months. They are published and ready to provide information to those users that need them.

Using no visuals also helped me in the accessibility department. If I use visuals, I must provide alternative text for the image so that visually-impaired users can also benefit from your document. No images, no alternative text :)

So, that is my experience.

I hope this article helps you question the need for visuals in your technical writing.