Should you add screenshots to documentation?

Since I saw 'walkme' many years ago I became a convert of the tour concept. I now use the o/s versions in javascript. Not based on research, but I find walking tours, ones that live inside the platform giving a 'learn by doing' experience can be an immersive, contextual hands on way to learn. They only fall out of date if you ignore them during product changes.

Of course, some users, and at some level, we all want the hard docs. This is where you're moving down the engagement funnel, from orientation to the deepest murk!

I saw just yesterday 'is there a printable version of the docs so I can read them offline?'. A fair, but rare, request to make a point - don't cater for everyone's _preferences_ - that is risky.

It's a balance - but one I think if you need a screenshot to explain it, you should also consider how much it needed explaining. Is it work a screenshot, or a UX review?

Yes, make a reference to a picture generated by opening puppeteer in your CI or CD pipeline when building prod.

> In my mind, an outdated screenshot is one of the fastest ways to lose customer trust, so if I’m not confident I can maintain the image, I don’t add it.

Now, this isn't the fault of the documentation workers, but the UI change that obsoletes the screenshot also obsoletes all the "mental screenshots" that people use to navigate the UI. You could make a case for adding screenshots as a means of applying cost back-pressure against unnecessary UI changes.

I think screenshots are good. Sometimes essential, in a crowded UI what you want is a nice screenshot with a huge red arrow saying "this control here". The animated screenshots used by e.g. VSCode are even better.

And there's a secondary market for youtube content for really visual users which shows the UI actually in operation, all the transitions, etc.

(Not discussed: localization. This multiplies up the work, but in some cases e.g. CJK vs Latin or RTL languages, the screenshots may look significantly different. Oh, and if you have an accessibility mode for e.g. red-green colourblind, might be nice to show that in action as well)

> In my mind, an outdated screenshot is one of the fastest ways to lose customer trust, so if I’m not confident I can maintain the image, I don’t add it.

But outdated documentation that describes how to do something in text that's changed is also infuriating to users.

A screenshot helps both users and future documentation maintainers determine if the instructions are out of date.

Yes, please and about documentation for command line programs, also adding example output (not only the command) can help a lot, especially if the reader is unexperienced with the tool.