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:

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 ‘Screenshot : Custom Installation – Database Configuration Wizard‘. 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😉

Ceci n'est pas un screenshot

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 8 March 2008, in Confluence, technical writing. Bookmark the permalink. 3 Comments.

  1. Adding a drop shadow around screen grabs helps make it obvious that they are images, eg:

    http://www.adaptavist.com/display/Builder/Options+Tab

  2. Hallo Guy, Thank you for this great suggestion. The Adaptavist docs look very neat indeed, and the drop shadow does make the screenshot stand out very nicely.

  3. In previous jobs I’ve “ripped” the images in half, applying a photoshop layer across cropped images.

    And we ALWAYS preface screenshots with “blah blah blah, for example:” As what the user has on screen may not reflect your screenshot (different font sizes, etc etc)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: