Make every screenshots count in your Confluence documentation

[#1]

One of my best contoured memories from my days in journalism is arguing with my editor-in-chief about a photo I chose for one of the international news pages.

He didn't like it. And found the photo important enough to intervene. A photo can make or break the page. Documentation is no different. A wall of text is offputing. But so is a bad screenshot you hoped would help the reader.

Screenshots, photos, graphics, and other forms of visual content have a role to play and information to carry.

Before you take a screenshot...

Think about what is the purpose of the image. Should it provide a ‘helicopter’ overview of the user interface? Focus on a specific clickable UI element?

Let’s explore some of the most frequent screenshot sins to put you on the right track.

Sin 1: Taking full-screen captures. Do you really need a full screen capture to tell users they need to click Customize theme.

Sin 2: Insisting that all screenshots are of the same size. Inevitably, this policy will make some text too small too read (see above) and some UI elements comically big.

There’s no perfect size but there is a (near) perfect policy. A screenshot should provide context specific to the action you expect users to take or to what they need to learn. Aim for balancing context, readability, and staying closely to the real life appearance. 

Let your screenshots talk

You may take THE perfect screenshot but you can go an extra mile pixel to help readers sail through your docs and accomplish the goal.

Cropping, blurring, and masking specific elements might be necessary to hide sensitive information. Another frequently used post-production trick is applying a light frame around the image, especially if both the page and the image have a white background (you can do that in Confluence).

To help users focus on a specific section of the image, use additional visual elements, such as arrows, frames, magnifiers… But use them subtly, your screenshot doesn’t have to be fancy but it should convey the right information.

Sin 3. A technical writer discovering the Tools menu and going overboard with knowledge...

Whatever you do, don't do THAT.

You might be tempted to use your company colors to highlight elements in your screenshots. That’s OK but do so with accessibility in mind.

Screenshots and Confluence

Now you have your great looking screenshots, but they're only one part of the bigger topic.

• How do you balance text and visuals?

• Can you scale up image management within Confluence?

• When should you use diagrams instead?

• What is your organization's policy for creating and using visuals within your organization?

As a part of our learning content efforts about using Confluence for documentation, we put together a comprehensive guide about best practices for using images in Confluence.

Important! There's an Easter Egg hidden in one of the screenshots in the linked guide. If you find it, let me know in the comments section :) 

P.S. That dispute with my then editor-in-chief? I won.

[Barbara Szczesniak]

Good stuff, @Kris Klima _K15t_! I document our company's main application for our Dev/QA team and internal users. When I started, my boss (a former tech writer) and I decided to limit the use of screenshots, since, as soon as you insert 1, that screen gets changed in the next sprint. 🤦🏻‍♀️I'd spend my days updating screenshot and have no time to write text.

Mostly, I just use screenshots in my chapter explaining the user interface. I may blur out the data in the shot, since that's not relevant; I'm just talking about the layout of the information and features. I use the step number feature of my screenshot software to insert big numbers on sections of the shot and then use that number in the text when I'm describing that section. 

[Kris Klima _K15t_]

Thank you for bringing this up @Barbara Szczesniak. I can relate!

Using just one introductory screenshot makes perfect sense for some types of products and product/user type combinations.

It allows users to make connection and find their way around. The rest of the UI is either intuitive or it conforms to general 'look and feel' for the type of product that you just don't need screenshots.

And I think it's a user (and writer) friendly solution.

A former colleague of mine is a loud proponent of 'no screenshot' policy on the grounds that 'if you need screenshots in your docs, talk to your UI/UX team to make it better' :) I actually interviewed for their company for the post of the docs manager and one of the first question I was asked was 'what do you think of screenshots' :) 

Having just worked with the their product and feeling lost, I said 'well, an intro screenshot would have been nice' :) 

On the other hand, sometimes you work with the audience where screenshots are necessary....