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

91–100 of 127 posts

Re: Should you add screenshots to documentation?

#91

Post by tairar »

ulrischa wrote: post #25

There are a lot of 'visual' people who learn very good with pictures and not so much with text. Mee too. A screenshot helps me getting into the setting. Later on I need some detailed documentation. That's why tutorial videos are so popular for beginning something new

Honestly I think you're getting closer to the core of the problem than most. Appealing to multiple different learning styles is a fantastic idea. I see tons of people online talking about learning by watching Youtube videos... this doesn't work for me, but it's obviously helpful for a lot of them. Some work well with text. I personally have a great measure of success when I'm presented with playgrounds for learning, like the GraphQL docs which let you live edit the queries in the documentation to play with them and see how the concepts work. None of these is any better than the others and all should be considered for the highest quality documentation.

Re: Should you add screenshots to documentation?

#92

Post by zbrozek »

I crave screenshots especially when the UI is very complicated. Documentation that tells me to engage the encabulator is hard to use when I don't know what the icon looks like or where it is or if there's a menu entry or how deeply nested it is or how to get it to take input.

There are tools which I use infrequently enough (e.g., GIMP, which I use about twice annually) that I don't really want to learn the tool. I want to get the job done and move on. Screenshots to help me navigate a UI, even if modestly outdated, are enormously helpful.

Re: Should you add screenshots to documentation?

#94

Post by jaktet »

jaktet wrote: post #88
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 haven’t used it in a long time and I’m guessing there might be something better now but I used to use “bro” instead of “man” when first starting out with a cli tool: http://bropages.org/ It’s documentation but with only examples.

Looks like bro pages is archived and they recommend https://github.com/tldr-pages/tldr or https://github.com/cheat/cheat

Re: Should you add screenshots to documentation?

#95

Post by ryandrake »

fellerts wrote: post #84
bingo-bongo wrote: post #19

Earlier quoted context omitted.

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.

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 just typed it in

SYNOPSIS - Explains the syntax and grammar of the command line options in an abstract way [OPTION...] HOST:SRC, and so on. Great if you're deeply studying the tool to learn all the edge cases of running it. Not as helpful if you want to do some specific thing.

DESCRIPTION - Pretty much marketing prose by the man page author. Useless.

OPTONS - Detailed, usually alphabetical(!!) list of each command line options. Great as a reference or if you want to know exactly what action X that known option Y does, but useless the other way around (I want to find the option Y that does known action X).

ENVIRONMENT - Interesting trivia about how the environment affects (or is affected by) the command.

EXAMPLES - THERE WE GO, THIS IS WHAT WE USUALLY WANT.

COMPATIBILITY - Interesting detail if you're on a weird platform or up against the edges of where the command is supported.

SEE ALSO - Useful if you don't even know which command you want.

STANDARDS - Nerd alert! You only care about this if you care what IEEE Std 1003.1-2001 is.

HISTORY - Yawn.

BUGS - Useful to know if it's not doing what you expect.

Re: Should you add screenshots to documentation?

#96

Post by squidbeak »

The article seems to miss one of the more important purposes of screenshots. They can compensate for weaknesses, points of confusion you may not realise exist in your docs, or any trouble with reading comprehension in your audience. At the very least, it's a courtesy to save your reader time.

Re: Should you add screenshots to documentation?

#97

Post by koinedad »

Up-to-date screenshots usually make things faster if I’m new to the product (which is usually why I’m looking at the documentation). But I think it’s 100% difficult to keep updated. Happened to me recently at work. I had to some documentation I wrote with screenshots and we moved to a different tool for the same purpose. More work for me to update now

Re: Should you add screenshots to documentation?

#98

Post by roydivision »

thaumasiotes wrote: post #71
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.

How so?

Re: Should you add screenshots to documentation?

#100

Post by RajT88 »

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 verbose documentation, and you still often don't get the parameters right on the first (or third) try.

This article for example is doing it right:

https://learn.microsoft.com/en-us/previous-versions/windows/...

Post reply on HN