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

71–80 of 127 posts

Re: Should you add screenshots to documentation?

#71

Post by thaumasiotes »

roydivision wrote: post #69

Please, please do not use screenshots of terminal sessions in documentation, there are so many reasons not to do this, no copy/paste, loss of textual data, harder to update/correct, size of document, etc. Instead make that little extra effort to use provided formatting in your wiki/blogging/word processing software using a non-proportional font and ideally appropriate syntax highlighting. Incidentally this also goes…

> 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.

Re: Should you add screenshots to documentation?

#72

Post by crispyambulance »

roydivision wrote: post #69

Please, please do not use screenshots of terminal sessions in documentation, there are so many reasons not to do this, no copy/paste, loss of textual data, harder to update/correct, size of document, etc. Instead make that little extra effort to use provided formatting in your wiki/blogging/word processing software using a non-proportional font and ideally appropriate syntax highlighting. Incidentally this also goes…

> Incidentally this also goes for chat and email.

Oh hell no. I agree with your point for documentation, but when you're trying to communicate something quickly, it's helpful to take a screenshot, apply a red circle and an arrow to point to an issue AS YOU SEE IT in your context.

It's fast, direct, and to the point.

And if there's need for more info, that can be followed up with in plain or formatted text and/or attachments.

Re: Should you add screenshots to documentation?

#73

Post by JKCalhoun »

fzeindl wrote: post #62
Max-q wrote: post #9

When learning something new, concrete is good, abstract is bad. Abstract thinking is good in the next step, when you already know the topic. Screenshot are very concrete and makes understanding the text so much easier. You know that you are in the right place, your brain gets to connect the text to the program. The same goes for command line programs: provide some concrete examples of how to use the program, not just…

Abstract vs concrete is not the main difference of images vs text. The main difference is that an image (without text in it) can relay a lot of information at once. Counter example: try reproducing an image from a description. A text on the other hand is able to give unambiguous explanation of relationships. Counter example: try painting “a primary and a secondary disk” as an image without any text. So images are goo…

> Counter example: try painting “a primary and a secondary disk”

Primary and secondary are kind of abstract concepts though. I think you're restating the relationship a little differently.

Re: Should you add screenshots to documentation?

#74

Post by JKCalhoun »

ratg13 wrote: post #21
Max-q wrote: post #9

When learning something new, concrete is good, abstract is bad. Abstract thinking is good in the next step, when you already know the topic. Screenshot are very concrete and makes understanding the text so much easier. You know that you are in the right place, your brain gets to connect the text to the program. The same goes for command line programs: provide some concrete examples of how to use the program, not just…

It's also extremely helpful in helping the user realize how out of date the documentation might be. Text just assumes you are both looking at the same thing. But with photos the user can realize there may have been UI changes that make the documentation you are looking at no longer accurate.

Or, "Hey, that looks like Windows — does this even run on a Mac?"

Re: Should you add screenshots to documentation?

#75

Post by scooke »

bingo-bongo wrote: post #19
Max-q wrote: post #9

When learning something new, concrete is good, abstract is bad. Abstract thinking is good in the next step, when you already know the topic. Screenshot are very concrete and makes understanding the text so much easier. You know that you are in the right place, your brain gets to connect the text to the program. The same goes for command line programs: provide some concrete examples of how to use the program, not just…

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.

This is true... I still often don't know if instructions for entering data should include the "" or the ...sometimes they seem to, often not. But seeing a screenshot would help.

Re: Should you add screenshots to documentation?

#76

Post by brianmcc »

Max-q wrote: post #9

When learning something new, concrete is good, abstract is bad. Abstract thinking is good in the next step, when you already know the topic. Screenshot are very concrete and makes understanding the text so much easier. You know that you are in the right place, your brain gets to connect the text to the program. The same goes for command line programs: provide some concrete examples of how to use the program, not just…

+1

Also, reference docs are not the same thing as tutorial/learning docs. The two should complement each other, but the latter should really focus on gently bringing in people new to a product, technology, ecosystem, whatever.

Shouldn't need to be said, but from experience, it does.

Re: Should you add screenshots to documentation?

#77

Post by opportune »

I think a small source of confusion/varying opinions here is that this is from the perspective of a technical writer. Technical writers are usually producing documentation for external users (author mentions "customers") as their key deliverable.

At least for me, I'm not too bothered by the docs I write looking a little unpolished or going out of date every now and then. Only a couple dozen people are likely to ever read it, it's not a big deal if I miss something because they'll know I wrote it and reach out directly if they need clarification, and as a corollary I'm mostly optimizing for "make it so explicit that they don't need to reach out for help, but not so verbose that they give up before reading it and reach out for help". Everyone knows it's a best-effort side task and you're not being held to a high standard - for guide-like documentation, just show the critical path most people care about and hope for the best.

When I consume official external documentation though, screenshots are a smell, especially in the case of "[having a screenshot] For every step in a task." You can't just message the writer to ask for clarification if you deviate from the happy path. So documenting the user-journey with screenshots instead of the functionality no longer works, because you have no real escape hatch as a confused user.

Re: Should you add screenshots to documentation?

#78

Post by opportune »

paol wrote: post #2

Target audience is a big factor too, I think the article failed to emphasize this. And, secondly, the nature of what is being documented. Do you remember when there used to be entire sections of bookstores dedicated to books like "Learn to use Word 98"? These books were always incredibly thick, so one time I opened one to find out how there could be so much to write about Word 98 (or whatever it was). Turns out it wa…

> Target audience is a big factor too, I think the article failed to emphasize this. And, secondly, the nature of what is being documented.

Right, I'd say screenshots are crucial for certain kinds of documentation and terribly amateurish for others. A guide walking you through a user journey in a UI should definitely have screenshots.

But there should be "real" documentation for things like APIs - if the only kind of documentation that exists for an API is guides with screenshots, you end up with a bunch of useless "hello world + a feature" documentation that doesn't help you understand the big picture, or how features/options interact.

Re: Should you add screenshots to documentation?

#79

Post by CM30 »

Of course, the visual reference can help clarify things that text alone can't explain. For example, take a simple task like 'fill in these fields in the config file'.

For someone with software development experience, it's pretty obvious what the needed format might be there, whether it's a JSON file, PHP file or in any other language you can think of.

But a new user might not know that. They might not know what's valid in a JSON structure, or that leaving out the quotes in a PHP variable's value will break things (especially if there's a space in the value they enter!)

Pairing somewhat detailed text instructions with a screenshot or diagram can help avoid this, and make it obvious how the information should be provided.

You could also use video footage along with the screenshots too if you have the time for it. It's a lot more work for sure, and I understand why most documentation creators don't do it, but it helps shows steps you might have forgotten while writing the docs, since it's very easy to leave info out or skip over things because they're like second nature to you.

Honestly, all three formats being available is probably the ideal here, but having at least the screenshots will make things significantly easier to understand at least.

Re: Should you add screenshots to documentation?

#80

Post by ReactiveJelly »

bingo-bongo wrote: post #19
Max-q wrote: post #9

When learning something new, concrete is good, abstract is bad. Abstract thinking is good in the next step, when you already know the topic. Screenshot are very concrete and makes understanding the text so much easier. You know that you are in the right place, your brain gets to connect the text to the program. The same goes for command line programs: provide some concrete examples of how to use the program, not just…

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.

I find myself craving examples for _everything_ even as someone experienced with a variety of tools.

So much documentation for APIs, CLI programs, _everything_ is painfully lacking in examples.

Or the examples will be just totally wrong or out of date, then search engines and LLMs slurp it up and give you bullshit examples when prompted.

So now a lot of my comments start with `// e.g.`

Post reply on HN