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

21–30 of 127 posts

Re: Should you add screenshots to documentation?

#21

Post by ratg13 »

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.

Re: Should you add screenshots to documentation?

#23

Post by Cthulhu_ »

One thing I wanted to do at my previous project (building a user interface for a complicated / specialized mobile network routing tool) was to add an end-to-end test suite (Cypress) that would set up the UI to a certain state and make a screenshot to ensure the screenshots used in the user documentation would be up to date at all time.

But, I never got the resources to build that UI (it was bigger than anything I'd ever been involved in, and all other projects were with a fully equipped team, this was a solo effort), so unfortunately that part went down the wayside as well.

Re: Should you add screenshots to documentation?

#24

Post by tristramb »

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…

Those books weren't much use in learning how to use the software. They were just easier to produce. They never explained the ideas behind the software. They just showed you the user interface. They treated everyone as if they didn't know how to use a menu.

Things are often the way they are because that way is easier to produce, not because it is useful.

Re: Should you add screenshots to documentation?

#25

Post by ulrischa »

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

Re: Should you add screenshots to documentation?

#27

Post by mebazaa »

I hate it when there’s a GitHub project that looks promising but makes you install a whole dev stack, run a script, and then go on localhost:666 before you can see the UI, as if it was a rite of passage.

I understand the arguments against publishing screenshots. But that’s how it feels to me as an external user. And frequently the UI tends to be disappointing. Personally, if I don’t see screenshots for a web or app GitHub project, I probably won’t touch it.

Re: Should you add screenshots to documentation?

#28

Post by blackoil »

Long back we made a software for some school. As help, we created screen recording showing simple things how to add or promote student etc. The request from school was that they want it as ppt with steps and screenshot. While initially we found it funny, it was much easier for users to follow it slide by slide than to remember all 5-15 steps required and making sure they aren't missing any.

Re: Should you add screenshots to documentation?

#29

Post by ExoticPearTree »

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 are good. In cluttered UIs it helps when they show you where to navigate.

Also, the author has a point: you need to keep the documentation up to date so the screenshots match the actual text. Because menus get moved around and it can be frustrating for non/semi-technical users if the screen they're looking at is not like in the documentation.

As a side note, it never crossed my mind that you can improve documentation by removing/deleting irrelevant icons/menus from the screenshots to make them more to the point without losing information.

Re: Should you add screenshots to documentation?

#30

Post by jzombie »

blackoil wrote: post #28

Long back we made a software for some school. As help, we created screen recording showing simple things how to add or promote student etc. The request from school was that they want it as ppt with steps and screenshot. While initially we found it funny, it was much easier for users to follow it slide by slide than to remember all 5-15 steps required and making sure they aren't missing any.

Slide by slide definitely seems much easier especially if a user interface has changed in any way since the documentation was made and the user still has to figure out how to navigate.
Post reply on HN