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 an instruction) or screenshots. I’ve described some tips on how to make 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 place 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 it’s 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 made a screenshot of the whole screen that UI is 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
Ok, a reader needs to click the cog wheel icon at first, so I’ll show them this icon.
And this is another mistake. People know how a cog wheel icon looks like. They need the 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 an 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 bit more information 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 show clearly where the cog wheel 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 steps 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 with 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.
