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

101–110 of 127 posts

Re: Should you add screenshots to documentation?

#101

Post by bbds »

RajT88 wrote: post #100

Documentation should have screenshots. Even more important - documentation should have examples of what valid parameter values are. Probably my biggest pet peeve in docs is describing what a param value should be, but leaving it up to you to figure out what that actually means. Sometimes there's a certain format expected, or several candidates for the parameter value. It drives me up the wall, that there can be very…

oh yes, 100% agree. Few months back I was given link to a repository in which I needed to add a configuration file in yaml format. In repository readme first thing I saw was a screenshot of a text editor with possible yaml objects and properties and a text description for them, second was a paragraph of vague description on how the tool that consumes this repo works. No text on yaml structure in readme, no schema, no validation, nothing.

Re: Should you add screenshots to documentation?

#103

Post by dylan604 »

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 reproducing an image from a description.

we now know the impetus for generative AI! someone couldn't understand the docs, and built a tool for it

Re: Should you add screenshots to documentation?

#104

Post by karaterobot »

If a screenshot isn't up to date, chances are the UI it depicts has changed as well, and the description of how to use the application is also out of date. I think it's an argument for not throwing documentation over a wall and never looking at it again, but rather including documentation updates as part of the requirements for a feature change.

The accessibility objection seems very weak. Yes, if you don't make an image accessible, it's not going to be accessible, that's tautologically true. So, don't do that!

Re: Should you add screenshots to documentation?

#105

Post by safeimp »

maicro wrote: post #83
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…

I've brought this up before, and even though I don't use the service much anymore, I still love Airtable's API documentation - they customize the API calls for the table you're actually on, so instead of the generic example of "say you want to create a new CAR entry linked to the SEDAN category, with the RED color property", it pulls the names of fields/etc. to use in the examples from your actual table. It's a small…

I always appreciate it when documentation does this. Is there a technical term for this implementation?

Re: Should you add screenshots to documentation?

#106

Post by LordShredda »

ryandrake wrote: post #95
fellerts wrote: post #84

Earlier quoted context omitted.

cheat.sh [0] has been a godsend when the man pages are too dense and I just want to use the tool and move on with my life. [0] http://cheat.sh/

I always thought man pages are not only too dense, but they put things in the wrong order. When I look up a man page I'm almost always trying to accomplish some task, so I am looking for instructions on how to do that task. But where are most EXAMPLES sections? At the very end or buried in the middle, if they exist at all! Look at the sections in a typical man page: NAME - Totally useless. I know what the name is, I…

I on the other hand am absolutely grateful for all the 'trivia' they throw in the manpages especially when trying to fix a problem withy system. It's the people that run into edge cases you want to help.

Re: Should you add screenshots to documentation?

#107

Post by freetonik »

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.

Anecdotal, but I do feel this when reading documentation for commercial products. I start to wonder, often unconsciously, whether the documentation is outdated (so, following it may lead to an error), or there isn't a good cooperation between designers and documentation writers (and the possibility that those are different people/teams doesn't feel too well, either), or the UI changes very rapidly (so I can expect possibly unwanted changes once I learn something).

Re: Should you add screenshots to documentation?

#108

Post by PeterisP »

samsquire wrote: post #58
chrismorgan wrote: post #45

Earlier quoted context omitted.

That’s an excellent example of a bad screenshot, something that should have been conveyed as text: File → Translate PlusCal Algorithm (Ctrl+T/⌘T) Later in the page there’s a potentially useful screenshot, https://www.learntla.com/_images/pluscal_run.png . But that first one shouldn’t have been a screenshot: it conveys roughly no value over text (a little value for some people, a negative value for others), and it imp…

When you're learning something for the first time, it can be hard to know what mental model you need to have to be effective with the tool. Some documentation is reference material. With reference material you might navigate the reference material in a particular traversal to get what you need to do what you want. How do I know some fact is important in reference material? The documentation for Git, Emacs or GCC is l…

I think the discussion is caused by different implicit understanding of what "documentation" means. Different types of documentation have different, conflicting needs; an amazing reference document is a horrible tutorial and an amazing tutorial is horrible for reference purposes. So you shouldn't try to make your reference material be useful as a tutorial, that way lies madness, make a separate document if you need one.

This is an interesting overview of these concepts - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

Re: Should you add screenshots to documentation?

#109

Post by stevefeinstein »

Screen shots shouldn't replace good text documentation. The Doc should work find without it. But screenshots can help with comprehension. As for letting screenshots become outdated, if you are updating the rest of the doc, why wouldn't you update the screenshots at the same time?

Re: Should you add screenshots to documentation?

#110

Post by esafak »

safeimp wrote: post #105
maicro wrote: post #83

Earlier quoted context omitted.

I've brought this up before, and even though I don't use the service much anymore, I still love Airtable's API documentation - they customize the API calls for the table you're actually on, so instead of the generic example of "say you want to create a new CAR entry linked to the SEDAN category, with the RED color property", it pulls the names of fields/etc. to use in the examples from your actual table. It's a small…

I always appreciate it when documentation does this. Is there a technical term for this implementation?

I suggest "Contextual examples"
Post reply on HN