Screenshots in Documentation
In order to make your documentation easy to interpret, you should not only write clearly but also add visual content such as photos (if you write instructions) or screenshots. I’ve described some tips on how to take the right photos for your documentation here: Photos in Technical Documentation. Now it’s time to talk about screenshots. This is also a difficult task — you have to add the right pictures in the right way. I will talk about the size of screenshots, design, and their placement in your documentation.
Think about your goal
Before you start, you need to set a goal. For example, I want to show a person how to contribute an article to my publication named “Technical Writing is Easy”. So, I should keep it in mind when I’m taking screenshots.
Size
Size errors come in two flavors: too big and too small. Let’s look at them.
Too big
Your screenshots shouldn’t communicate too much information, as shown in the picture below:
It confuses readers and doesn’t show what is important and what they should do. The problem is — I’ve taken a screenshot of the whole screen, making the UI hardly visible.
It’s still too big
Well, you have understood your mistake and taken a screenshot of an entire window to help a reader have a clue what they should do.
And it’s another mistake — the whole article text and steps are captured, so a reader doesn’t know where to look first. Readers don’t need so much visual information, just clear steps.
Too small
Okay, a reader needs to click the cogwheel icon first, so I’ll show them this icon.
And this is another mistake. People know how a cogwheel icon looks like. They need context. Of course, it’s easy to find this button on Medium because the UI is minimalistic, but it’s just an example, and more often than not, technical writers write documentation for more sophisticated tools where the interface is more complicated than on Medium, and finding the icon you are documenting can be like hunting for a needle in a haystack.
It’s still too small
Well, it’s better but not that we need. You should give a little more information about where this button resides in relation to the entire application interface.
That’s what we need
Through this screenshot, we provide useful information that doesn’t confuse readers and clearly shows where the cogwheel icon resides.
Design
However, it’s not enough. You can make your screenshots better even when you think that they are perfect. Design your screenshots by adding some highlights. Here is an example:
I use rectangles and numbers to show what a reader should do and in what sequence. However, be careful with colors — I’ve used bright colors for the following screenshot, and here is the result:
Colors are too bright, and it’s difficult to concentrate on the screenshot. Also, numbers are not obvious, so you need to strain your eyes to see clearly the steps.
Moreover, I also add torn and shadow edges. The torn edge helps to show the borders of the interface to help readers quickly orient themselves. The shadow edge helps to separate a text and a screenshot.
Place
Of course, visual content is a great tool that clarifies documentation, but it should not consists of pictures only. You should separate every picture with some step descriptions.
How you should not do:
How you should do:
If you want to show only steps without text descriptions, create a video or a GIF.
Plus, don’t place a screenshot far from its description; it should not look like this:
Conclusion
I hope this guide to the most important principles of taking screenshots and how to use them in your documentation has helped you realize that visual content is essential. You should not take a screenshot randomly and place it randomly as well. Keep in mind that people will read your manuals, instructions, or whatever, so make it people-oriented.
I recommend you to have a look at Marshall’s article called “Google Docs tips that will save you time and make your day”. I think it’s a good example of using GIFs and screenshots in a user guide.
How did I become a technical writer? What skills do you need? Read FAQ on Technical Writing.
