Illustrations and screenshots are the most visually appealing part of technical documentation. In a stream of text, eyes naturally gravitate to images. They break the monotony of text and offer relief. Everybody likes a bit of color.

A carefully composed screenshot is packed with information. Best screenshots don’t show just an empty screen. They show sample data and expected input.

Expected parameter format

Filled-in screens are always better than empty screens. A great screenshot can give the reader an idea, shortcut, or an opportunity for a quick solution — without even reading the text.

Screenshots are tedious to maintain

As useful as screenshots are, I find them tedious to maintain. My writer colleagues and I hated taking screenshots because we knew the maintenance pain that awaited.

Text is easy to revise but images are tedious. Here’s why:

  1. Screenshots illustrate scenarios. The best screenshots show a complete set of inputs. Meaningful sample data demonstrates the purpose of a screen much better than random input or no input at all. When you update such screenshots you have to recreate the scenario. This means leaving documentation, feeding the sample data into the product, and coming back with a screenshot. The doc-product-doc roundtrip is time consuming.
  2. You can’t find invalid screenshots. The fundamental problem with binary content is that you don’t know if current screenshots are out-of-date because you can’t find them. No matter how diligent you are with file naming and metadata the binary content itself is not indexed. You might know exactly what the outdated data is but you can’t find where it exists. It’s maddening, really.
  3. New features come often. At Magnolia, we release the product 15 times a year on average. These releases introduce new features and improve existing functionality. They often invalidate current screenshots.

How about crowdsourcing the work?

The inability to search for invalid screenshot bugged us. Computers could not find data locked in binary content so why not replace them with individuals? Use human intelligence to perform tasks that computers are unable to do.

We thought about organizing a doc sprint to find and update invalid screenshots in documentation.

A doc sprint is a short (two to three day) event when a group of people collaborate to develop a specific set of tutorials, often including the associated code.

Doc sprints (“Screenshot Jam”, “Image Bash”, be creative!) are a great way to bond with your developer colleagues. You get some documentation and have fun working together.

However, you should be careful how you frame the task. Crowdsourcing works well for tasks that are motivating such as “We need better tutorials for our API”. A creative task can spur colleagues to write or review content. Hunting for invalid screenshots is not very motivating to be honest.

Trust is our currency

Does it really matter if screenshots are out of date? Isn’t the accompanying text more important?

Accuracy matters in technical documentation. If a screenshot does not match what the user sees on the screen then trust starts to erode.

Inaccurate documentation is the worst of the 10 Reasons Developers Hate Your API. Trust is paramount. A sales pitch may exaggerate, marketing may boast, but technical documentation must be precise.

Making screenshots editable

We had an uneasy feeling that the issue was getting worse. With each release we got more material to maintain. More docs, more screenshots. So we decided on a radically different approach: replace images with text.

Statistics: how many images

We ran the numbers. Magnolia documentation had about 2,000 screenshots. The most common subject was the Configuration app. The app is basically just a table: rows and columns and text. Apart from the icons, there are no images.

We estimated that 40% of all screenshots showed the configuration tree.

This finding was both embarrassing and promising. Embarrassing because we had taken so many screenshots of something that was basically just text. But promising because the prospect of turning 40% of images into editable text could eliminate half the time sink.

Converting trees into tables

We recreated the configuration tree as a table in Confluence wiki. Here’s what it looks like in edit mode:

Editing a table in Confluence

Couple of things to note:

  • Icon fonts. The tree node icons come from an icon font. Icon fonts are awesome because you can change their size and color instantly with CSS. We started using the same Magnolia Icons font that is used in the product UI. This level of reuse made us writers feel pretty cutting edge. The only aggravating detail is how we add the icons. A little helper macro is necessary because adding your own custom symbols to the Confluence symbols menu is not straightforward.
  • CSS class. We wrap the table in a Table Plus macro to assign a CSS class. This allows us to style the borders and colors so it looks like the product.
  • Hierarchy. A tree is a hierarchical structure. In documentation we fake the hierarchy with indents. For presentation purposes it doesn’t matter but it makes the table much easier to edit. Ease of editing is a big deal because many non-writers contribute to Magnolia documentation. A casual user who wants to add such a table can copy-paste it from elsewhere and just indent their way to perfection.

This is what the reader sees after we save the page:

The result is incredibly similar to the product, nearly identical.


Turning images into tables provided some unique benefits:

  • Everything is searchable. All the text that used to be trapped in images is now indexed. Googlebot crawls Magnolia documentation since it’s public and indexes the text inside the new tables. Users can search for a property name and find examples of usage. Editors can find where a certain configuration is used. We feel like a silo of closed content has been opened.
  • Changes are quick. Writers no longer worry about having to reproduce elaborate scenarios to take a screenshot. Changes are quick to do. We edit “screenshots” just as we would edit text.
  • Copy-paste works! Users can copy text from screenshots and paste it into their system. This is very useful for long values such as fully-qualified Java class names that must be typed correctly.

Future-proof mechanism

What happens when the product changes? What if the tree looks different in the next version?

We already have tickets asking for usability improvements. The vertical alignment of nodes in the tree is not ideal. It is hard to see the parent node when the tree is tall. Readability suffers as complexity grows, and so on. The tree will change soon.

That’s OK. The table method is future proof. We can change the CSS to update all tables instantly. We don’t need to edit each table. Improved change management is a classic benefit of separating content from presentation. Style should not hard-coded into each piece of content but rather referenced from CSS. Experiencing this benefit in our own content was eye opening.

Treachery of Images

Finally, you might be wondering why we use a drop shadow around the configuration table. It’s not an image so why the makeup? Falsifying perfectly good text!

There’s a reason: The Treachery of Images. We add a drop shadow to all images so that users don’t confuse documentation with the actual product.

You may think this is foolishness but it actually happens. Sarah Maddox wrote about a funny, but very true, case where readers clicked on buttons in a screenshot and complained that they didn’t work.

As the product and its documentation look more alike, it is no longer clear which is which. Is that a clickable button or just a representation?

The direction in which API documentation is heading makes the line even more blurred. You can already embed functional examples into documentation. The docs effectively become actionable.

At Magnolia we use the Swagger API Explorer to help users learn our REST API. Swagger is embedded into the product. It shows what parameters and options the API accepts and it responds to your requests.

Swagger acts as live documentation that is always up-to-date. So we are already at the point where you can type input into documentation and get a response.

The little drop shadow that separates non-functional elements from the functional is not visual vanity. It’s error prevention.

Technical Documentation

Best of developer docs

    Antti Hietala

    Written by

    Product manager, average skier, awful fisherman. Yes-hat wearer. Fan of hot glue.

    Technical Documentation

    Best of developer docs

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade