Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Should you add screenshots to documentation?

thisisimportant.net

Post reply on HN
Print view View original

121–127 of 127 posts

Re: Should you add screenshots to documentation?

#121

Post by m1keil »

I don't have issue with screenshots in docs except for one small caveat: too many screenshots.

Don't screenshot Every. Single. Step. Doing so makes the documents harder to read as every paragraph ends up seperated by one or more screenshots.

Make sure that "the point" of the screenshot is clear. If required, crop or highlight the important bits.

Granted, screenshots will go out of date but so will any other documentation. This is also why having bit less screenshots will help you keeping docs up to date.

If you still think that screenshoting every step is a better idea, consider screen recording instead.

Re: Should you add screenshots to documentation?

#122

Post by thaumasiotes »

roydivision wrote: post #98
thaumasiotes wrote: post #71

Earlier quoted context omitted.

> there are so many reasons not to do this > no copy/paste That would be a benefit of using screenshots, not a reason not to use them.

How so?

Copying and pasting seriously inhibits learning and tends to directly cause mistakes.

Re: Should you add screenshots to documentation?

#123

Post by smore »

politelemon wrote: post #102

> Outdated screenshots can cause customers to lose trust in documentation accuracy. Do you have a source for this? I've not experienced similar feelings when looking at older outdated screenshots, but I do when finding incorrect instructions.

Thanks for reading! The source is my experience working in the industry and interacting with other technical writers and customer feedback submitted on doc pages, posted in Slack communities, and more. I've spent years reading comments from readers asking for updated documentation because it has a screenshot of a different UI than the one they use—even though the rest of the content is accurate.

It's difficult to find published research about technical documentation because basically only Nielsen Norman Group is doing extensive research on web content. Baymard Institute, who I link to in the post, also does quite a bit of research but even more broadly and mostly on overall website and web marketing content.

Re: Should you add screenshots to documentation?

#124

Post by BoppreH »

pjc50 wrote: post #15

> 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-pres…

That's a really insightful view.

Perhaps one can extend it to automated UI tests too: if it breaks a test by moving an element/adding a popup/changing the flow/taking longer, then it would probably undermine existing users' expertise. What used to be a fragile test is now the canary in the coal mine.

Re: Should you add screenshots to documentation?

#126

Post by woodrowbarlow »

woodrowbarlow wrote: post #87
Tempest1981 wrote: post #5

Are there tools/IDEs where you can attach screenshots or sketches to code (source files)? More integrated than a README with images, ideally. I understand the out-of-date concern... still interested in how it might work. Feels like something that probably existed in the 90s as part of some bespoke ecosystem.

you might be interested in "literate programming", a technique pioneered by Donald Knuth. the idea is to write your code in steps, inserting notes and documentation into each step. you can then use tools to "weave" (produce documentation) or "tangle" (produce runnable code). note: to do this properly, it should involve more than just inserting notes into your code. you'll need to adapt the way you write and design yo…

here's a retroactively funny snippet from the original knuthweb paper:

> I chose the name WEB partly because it was one of the few three-letter words of English that hadn't already been applied to computers.

Re: Should you add screenshots to documentation?

#127

Post by scantron4 »

rcxdude wrote: post #33
d--b wrote: post #18

> Outdated screenshots can cause customers to lose trust in documentation accuracy. as opposed to outdated documentation without screenshots, where the user has no idea that he's reading stuff from 5 years ago?

Indeed. I lose a lot more trust when I've spent 15 minutes trying to find the damn option the documentation insists should be there, only to find it doesn't exist any more. A screenshot at least gives me that information faster.

This is what I was going to say. Nothing more frustrating than trying to find an option that has been moved somewhere else (why is android documentation the worst about this). At least with a screenshot you know it is either where they say it is or that you need to find a different tutorial.
Post reply on HN