Ceci n’est pas un screenshot
The Treachery of Images takes on a whole new meaning for technical writers. A screenshot can be so realistic that it’s positively misleading. Especially when accompanied by text that says something like, ‘Click the dropdown list on the screen’.
I’m busy reworking the installation and setup guides for our wiki product, Confluence. I’ve come across a page which triggered a funny memory from my first few days on the job. Take a look at this page, which contains some text and a screenshot:
Screenshot — Ceci n’est pas un screenshot:
Part of my job as tech writer on a technical documentation wiki is to monitor customers’ comments on the documentation pages. A short while after I started this job, a customer added a comment to the above page, saying something like:
The database configuration screen is broken. Nothing happens when I click the database drop-down menu.
Very soon, two other customers replied that they had the same problem.
We had just released a new version of Confluence, so I took this problem seriously and reported it to the development team. They could find nothing wrong with the product. Then another customer pointed out that people should try clicking the application screen rather than the documentation screenshot!
At that time, the above documentation page did not contain the words ‘as shown in the screenshot below‘, nor ‘‘. I added those as soon as I realised what was happening.
Now that I’m doing a big rewrite of the installation and setup documents, I’m going to add a big friendly ‘don’t panic’ sort of message, saying something like this:
Hint: The above image and all the images on this page are screenshots. Clicking an image will not install Confluence.
It may sound a bit naive, to be duped into clicking a screenshot rather than the living and breathing application screen. But when you consider that the Confluence application is a web application, and the documentation is a web page too, and the documentation is hosted on Confluence itself what’s more…. Well, it’s a pretty easy mistake to make!
Other things we could do: Add a watermark or callout on every screenshot; put a border around a screenshot, so that it’s clearly separate from the text; …
Have you had any such experiences, and what techniques do you use to avoid misunderstandings?
Ah, the treachery of images. What’s real (read the first paragraph on the linked page — it’s awesome) and what’s not? It’s a tech writer’s job to clarify that small but non-trivial matter. I think I might have mentioned before that this leads to the inescapable conclusion that documentation is at the centre of the life, the universe and everything😉
BTW if you really do want to install Confluence, this button really will work. Really😉