Archives for 

technical writing

Screenshots in User Documentation – An Opinion Piece

Last year, the most eloquent and investigative Earnsy Liu wrote a nice little article for TechCommNZ summing up the opinions and research (or lack of) into the use of screenshots in user documentation. It’s something I’ve always been interested in, as a long-time software documenter and creator of screenshots.

Based on my recent experience as both a tech communicator and IT trainer, I have outlined a number of benefits and drawbacks to using screenshots in user documentation, as well as a few recommendations. Read on, unless you’d rather see a picture, in which case you’re out of luck!

Benefits of using screenshots in user documentation

  • Gives me the excuse to use Techsmith’s Snagit ‒ that most wonderful and miraculous tool. And I can use the sexy jagged-edge effect!
  • Makes writing user documentation more fun ‒ you get the chance to play with graphics editors, data, image types, and figure out all the issues related to this.
  • Can improve the appearance of the documentation, adding colour and breaking up the page.
  • Gives more of an instant appeal to users ‒ maybe a pretty picture will draw them into the text?
  • Gives users a nice visual reference ‒ a way of checking their screen against the instructions. This is particularly useful if a user already knows how to do the process, but they just need a reminder.
  • Allows you to reduce the number of words in the instruction, as a screenshot can often replace a more detailed explanation ‒ but be careful if your content needs to be accessible to diverse audiences (see below).
  • Gives you the opportunity to point out specific parts of a screen, for example, an important field or check-box or a menu item etc.
  • Appeals to management, especially those who are subscribe to the (largely debunked)  “learning styles” theory.

Disadvantages

  • Increases documentation time considerably. If including screenshots, you will need to factor in the time it takes to create/find suitable data for your screenshots, set up your screens, take the screenshot, add call-outs/notes/highlighting, and then insert the screenshot into the authoring tool. You should also set aside time to create a set of rules or a style guide around the use of screenshots.
  • Creates challenges when updating user instructions, as screenshots often take more time to update than text. Also, sometimes the screenshots need updating simply because the UI gets an upgrade or changes colour.
  • Risks confusing the user if something is not quite right in the screenshot. For example, if your screen shows an additional field or slightly different layout, the user may get confused and not follow the instructions. This is a particular issue when documenting any system that allows users to personalise their settings and themes, or that presents different options based on a user’s access permissions.
  • Risks distracting the user from reading the text ‒ if they only look at the screenshot and don’t bother to read the important notes or instructions. You can slightly mitigate this risk by putting text call-outs into the picture, although this creates further updating hassles.
  • Makes your documentation much longer (page count when printed or scrolling concerns when viewing online), and can create hassles with printing, for example if your screenshots are too wide for the printed page. You can set the pictures not to print and you can set a maximum width for your screenshots.
  • If you have used screenshots to reduce or replace words, anyone relying on a screen-reader to read your content will miss vital information, even if you supply some ‘alt’ text.
  • Risks your reputation if you inadvertently include sensitive data in a screenshot.

Screenshot1

Users do look at screenshots

I have found that users really do look at the screenshots, and often they will do this in favour of reading the text. I know this based on training sessions I have run with dozens of users of my documentation. This is both an advantage and a disadvantage:

  • It means that you need to take extreme care with your screenshots, to ensure that they are accurate, relevant, and show correct data, because if anything is wrong, your users will notice.
  • On the other hand, if you have something very important you want to highlight, find a way to include it in the screenshot and I guarantee your users will notice it.

Conclusion

Overall, I think that despite the disadvantages, screenshots do have their place, even in online docs. But if you have limited budget or limited time, don’t feel too bad leaving them out. If your writing is clear and you have structured your documentation well, the users should manage just fine.

If you do want to use screenshots, here a few of my recommendations

  • Spend time before you create your first screenshot to document your rules and styles (min and max sizes, colours, jagged edge or other effects, call-out and highlighting styles, and so on). And then stick to your rules!
  • Think about how the screenshots will look online, on paper, and on mobile devices, and design accordingly. Maybe you can provide users with alternative options such as clicking a link to view a screenshot, or just seeing a thumbnail.
  • If you get time, do some testing with your proposed screenshot method and type, size etc. If you can user test, that’s even better.
  • Investigate ways of keeping the file size of your screenshots low, and play around with changing your resolution or changing the application window size to keep the width to a minimum.
  • Set up the application you are documenting as close as possible to what your users will see ‒ aim for the most standard set-up. If using a development or test environment, make sure you have a way of manipulating the colours to match the production environment and remove any watermarks. Make friends with the IS team to see what they can do for you in this respect.
  • Set up some test data if possible, but don’t waste a lot of time on dummy records, Joe Bloggs users, and so on. It can be difficult setting up dummy data for all the scenarios you are likely to need.
  • Avoid using text call-outs unless you are dealing with a very low-skilled audience. The time it takes to create and maintain these doesn’t it make it worthwhile. However, if you do use them, make sure you save the file in a “native” format, such as .snag for Snagit, so that when you come back to edit your screenshots you have access to edit the call-outs too.
  • Set up a good naming convention for screenshots, and a good filing system.
  • Use judicious highlighting or image call-outs such as drawing shapes around important screen areas ‒ but keep it simple.
  • Decide if you will always capture the full screen or just a section of the screen (I prefer the latter option).
  • Choose a great screenshotting tool, preferably one that lets you edit the screenshots as well. I recommend Snagit, but there are many others out there and some are free. For example, Greenshot, Irfranview, Fullshot, or even the humble Snipping Tool. Just don’t use Printscreen!

So, those are my current thoughts. As usual, I’m quite willing to be swayed by good evidence or a lively argument, and I welcome your comments below. What do you think? Do you have any more tips or suggestions?

A work of satisfiction

The following post first appeared as the foreword to the November 2015 issue of Southern Communicator. Satisfice¹ (verb). To decide on and pursue a course of action that will satisfy the minimum requirements necessary to achieve a particular goal. In this article I’m going out on a limb to ask whether there is a place in publishing […] Continue reading →

Book Review: Rewrite – How to overcome daily sabotage of your brand and profit

Last weekend I sat in the autumn sun and read Rewrite: How to overcome daily sabotage of your brand and profit, by Lynda Harris of Write Ltd. Lynda has succeeded in creating an essential weapon for individuals who have the will to conquer costly writing habits in their organisation. As you would expect from the chief executive of Write, […] Continue reading →