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

61–70 of 127 posts

Re: Should you add screenshots to documentation?

#61

Post by yread »

stephenr wrote: post #48
yread wrote: post #46

Earlier quoted context omitted.

It's a complex tool with lots of hard to discover features. Training can be more efficient than watching youtubers use it since you can ask questions

> more efficient than watching youtubers That isn't really saying much. "Watching YouTubers" doesn't really seem like a way to learn how to do something, it seems like a way to waste some time and pretend you're one of the cool kids. I can't be the only person who remembers when people learnt how to use a program by using it ?

"Using it" is fine for a simple tool. But IDE is a complex beast. You can easily fall into a local optimum without discovering and using the best features. Think using arrow keys to navigate in vim. It works, gets the job done but is far from optimal. You could read the manual but I'm sure you agree that training is a lot more efficient use of your time

Re: Should you add screenshots to documentation?

#62

Post by fzeindl »

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 good to give an overview fast, but text is needed to make it unambiguous.

Re: Should you add screenshots to documentation?

#63

Post by samsquire »

chrismorgan wrote: post #59
samsquire wrote: post #58

Earlier quoted context omitted.

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…

Um… are we talking about the same thing? It’s a menu . This is basic computer usage. Mentioning the menu path is just as good as a screenshot (better, in my opinion), and takes much less space and requires less maintenance. If you actually need to explain what a menu is and how to use one, the screenshot genuinely won’t help. And when this is intended just as a reminder of what has already been covered, a screenshot…

I will try to explain.

My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox".

It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal.

I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is SO obvious that there was a missing step required in my mental model of how TLA+ works.

A beginner to IntellIJ needs to be taught that the "Play button" is what they're looking for, and a screenshot puts that into context.

Blender is a complicated piece of software, if you had text based descriptions of that tool - I wonder how useful that would be to understanding where similar functionality is placed. Compared to a screenshot WITH CONTEXT.

My case highlights how even what seems like a trivial screenshot can actually help people contextualise something that is basic to you.

Do basic features go in context menus, toolbars, or hidden in menus.

The text "Go to File -> Translate TLA+ algorithm" would be missed if it was in a big document in the middle, as if it's just a fact.

The screenshot says "This is important, pay attention".

Re: Should you add screenshots to documentation?

#64

Post by chrismorgan »

samsquire wrote: post #63
chrismorgan wrote: post #59

Earlier quoted context omitted.

Um… are we talking about the same thing? It’s a menu . This is basic computer usage. Mentioning the menu path is just as good as a screenshot (better, in my opinion), and takes much less space and requires less maintenance. If you actually need to explain what a menu is and how to use one, the screenshot genuinely won’t help. And when this is intended just as a reminder of what has already been covered, a screenshot…

I will try to explain. My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox". It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal. I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is…

This would seem entirely adequate to me:

> We discussed how to translate the pluscal in Setup, but as a refresher, it’s File → Translate PlusCal Algorithm in the menu (Ctrl+T/⌘T by keyboard). This puts a translation below the comment block:

Also, if it’s an easily-missed step and something just mysteriously doesn’t work if you miss it out, that’s not a documentation bug, that’s a design bug. (I’m not familiar with it.)

Re: Should you add screenshots to documentation?

#65

Post by rmoriz »

When I was at school they told us people learn differently. Through examples, through listening to loud reading and by doing (e.g. applying things). I for one can learn fast through examples and visual representation. A wall of text can be very frustrating so I personally like screenshots when appropriate.

I support the author's points, that screenshots must come with a description what or why something has to be done. Not just "click this and that and you will be done". I also strongly support the remarks about automation of screenshots. Outdated screenshots are the worst.

Re: Should you add screenshots to documentation?

#66

Post by stephenr »

samsquire wrote: post #60
stephenr wrote: post #42

Earlier quoted context omitted.

> If you didn't have any training in IntelliJ People get trained to use an IDE? I gotta say, I've been using IDEA since 2015, and a language-specific IntelliJ based IDE since 2013, and in 10 years of use it's never occurred to me that someone might need training to use it.

Did you train yourself? On my first day of work I was given access to SVN and then had to piece together how to run the project. So I was bouncing around IntellIJ and all the various tools to make up a modern development environment. In week-0 of an iteration you might just be spending time to get a development environment working. If you wanted to get something working, did you ask your colleague "how to get company…

I don't use IDEA for Java work, I use it because it's the only IntelliJ platform app that supports "all" languages (or at least all the languages I care about), but sure let's go with your examples above.

If you're hiring someone to do java work, who has no experience of jar files, or java build tools, them not being able to use IDEA is the least of your concern.

This is like saying "on the first day of work as a carpenter, we send all new hires on an intensive nail-gun training course, because they probably don't know how to use a circular saw, or even what the pointy end of a nail is for"

I don't know what schools teach these days, but all the classes I had (one of which, coincidentally enough was java) specifically made us not use an IDE - we had to use a text editor for all practical work.

Once you know what you actually need/want to do, using a different tool to achieve it is generally not a complex task.

If someone knows how to use a screw driver, they don't need comprehensive training to then use an electric drill/driver to put a screw in.

If they don't know how to use a screw driver, giving them a drill/driver to learn, is a fucking terrible idea.

Re: Should you add screenshots to documentation?

#67

Post by smoe »

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…

Screenshots also help a lot when the tutorial is not in your native language. When I learned Photoshop as a teenager, my UI was in German, but most of the good tutorials were in English. The screenshots really made it easier to locate things in the menus when I didn’t know a word yet, or a non-obvious translation was used.

Re: Should you add screenshots to documentation?

#68

Post by KineticLensman »

floweronthehill wrote: post #50
debesyla wrote: post #34

Earlier quoted context omitted.

Indeed. I have tried to learn more modern web developement recently and lot of tutorials start with "just put this into console" and I'm stuck with wtf are all these strange tools, give back my good old days of just dropping files through FTP, haha. Screenshotted tutorials help me lots.

This is why I like to watch YouTube tutorials sometimes, especially when I’m new to a certain topic. They show every step clearly. The author can’t forget to mention a piece of information because he’s doing it in real time. Too often with written tutorials there’s one or more steps missing, that are obvious to the author but not necessarily to someone new to the subject.

Yes although this requires the author to assess what they are showing to see if it makes sense from a teaching / learning perspective.

I remember watching a tutorial about a new feature in Photoshop. The author

* showed some results

* showed how the older version of the feature worked (assuming we were all familiar with it)

* did 'undo' multiple times to get back to the original image

* started showing the sequence of steps to use the new feature

* realised they had made a mistake and undid some of the steps

* restarted from the point where they had made the mistake.

I had to watch this about five times to work out the actual minimal sequence of steps involved. Some editing or a retake would really have helped here.

Re: Should you add screenshots to documentation?

#69

Post by roydivision »

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 for chat and email.

Re: Should you add screenshots to documentation?

#70

Post by triyambakam »

hitchstory wrote: post #4

For those interested in the concept of having guaranteed/permanently up-to-date documentation (with or without screenshots) I built this testing framework based upon autogenerating good how-to or reference docs from tests: https://github.com/hitchdev/hitchstory (the website example has screenshots generated by playwright, the REST API example has real tested JSON snippets, the command line example has command outputs…

Exactly what I was hoping to find in the comments. Thank you
Post reply on HN