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

51–60 of 127 posts

Re: Should you add screenshots to documentation?

#51

Post by Aachen »

Interesting article.

My opinion when clicking: definitely yes, they're super helpful to see in a glance what it's supposed to look like and where I'm supposed to click

My opinion after clicking: rarely, because you'd need to capture them in every language/region and recapture them after any significant UI change and make sure it's small enough for users to see who need 400% zoom or are viewing it on a phone screen and you need the text equivalent anyway for blind people

That's not what the author wrote, just my takeaway. The author has recommendations for how to make screenshots work for you, but even with automated screenshot grabbing, it feels like you can count the number of UI updates that can happen until the page doesn't match the textual description anymore (or the URL changes, or the button ID changes so the screenshot grabber can't find the page anymore altogether) on one hand, if not half a hand, so you need to check them all manually after every update anyhow

They're still good for marketing material such as a readme file or project website. I love screenshots because they show features more clearly than the text description and you can see at a glance how easy they'll be to use and whether the offered options match your requirements. That's just a handful of representative screencaps though, not an extensive set that needs to match precisely with a user's steps, so much more maintainable

Re: Should you add screenshots to documentation?

#52

Post by GuB-42 »

pjc50 wrote: post #15

> In my mind, an outdated screenshot is one of the fastest ways to lose customer trust, so if I’m not confident I can maintain the image, I don’t add it. Now, this isn't the fault of the documentation workers, but the UI change that obsoletes the screenshot also obsoletes all the "mental screenshots" that people use to navigate the UI. You could make a case for adding screenshots as a means of applying cost back-pres…

> You could make a case for adding screenshots as a means of applying cost back-pressure against unnecessary UI changes.

Totally agree. As for localization, if you localize your documentation, of course, the screenshots should be in the correct locale.

However, it may be a problem when there are elements you don't control. Native UI toolkits make the appearance match that of the system. And while I think it is a good thing (I hate the modern trend where no effort is done on integration with the host system), it means that your screenshots may not match, for example if the user, doesn't use the same Windows version as you do. It is particularly true on Linux desktops where each distro has its own theme.

Re: Should you add screenshots to documentation?

#54

Post by marginalia_nu »

ExoticPearTree wrote: post #29
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 d…

> In cluttered UIs it helps when they show you where to navigate.

They're also good in minimalist UIs, which can be just as difficult to navigate if not more so. The difficulty stemming from the such UIs typically only showing you what's related to the current task, making it difficult to know if you're in the path that progresses toward your goal (if your goal extends beyond task in view).

Re: Should you add screenshots to documentation?

#56

Post by harywilke »

samsquire wrote: post #12

I think documentation MUST have screenshots. I was recently trying to work out TLA+ in TLA Toolbox and there is there is this screenshot in the documentation on this page on PlusCal: https://www.learntla.com/core/pluscal.html The screenshot about going to File menu and clicking "Translate PlusCal Algorithm" was invaluable! Now I can learn that Ctrl+T is the shortcut to run the translation. EDIT: Before this point I w…

The screenshot could be more clear by highlighting 'file' and 'Translate PlusCal Algoritm'. This could be useful in skimming the documentation, but i think this could be a case of where text would be the clearer option.

Re: Should you add screenshots to documentation?

#58

Post by samsquire »

chrismorgan wrote: post #45
samsquire wrote: post #12

I think documentation MUST have screenshots. I was recently trying to work out TLA+ in TLA Toolbox and there is there is this screenshot in the documentation on this page on PlusCal: https://www.learntla.com/core/pluscal.html The screenshot about going to File menu and clicking "Translate PlusCal Algorithm" was invaluable! Now I can learn that Ctrl+T is the shortcut to run the translation. EDIT: Before this point I w…

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 large and it is not immediately obvious what information is important, yet.

But at the beginning of your journey, you need to be taught a "flow" an expected pattern of operation to build up the right mental model of how an average session with the tool works. For programming this might be the edit file, compile, run, debug loop, or TDD or IntelliJ's build and deploy. Or a CI system commit, push, deploy, promote cycle. Or kubernetes kubectl edit, apply.

I opened the "dining philosophers TLA+" example and ran it - this seemed to be an affordance of the TLA+ Toolbox GUI which was straightforward to understand.

But then I tried to use the tool with my own. I interpreted the existing code of the dining philosophers and tried to make my own ringbuffer model.

It took me a while to realise that some of the code in the dining philosophers code was generated from another section.

It took me a while that I needed to update this screen to put in the following details that I have filled in on the screenshot:

https://github.com/samsquire/assembly/blob/main/screenshots/...

You have to put your entrypoint in the "temporal formula" and then put your model arguments on the right hand side.

I was able to piece together the operation of this tool by piecing together various reference details together, it wasn't until I saw that screenshot I referenced in my OP that I realised I needed to do that step to get the PlusCal code to update the TLC code that follows it. I was wondering why it didn't work until I saw that screenshot.

Re: Should you add screenshots to documentation?

#59

Post by chrismorgan »

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…

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 is even more inappropriate.

I’m not saying there should be nothing there. I’m saying that the screenshot should have been text. I’m genuinely baffled about what you’re actually saying.

Re: Should you add screenshots to documentation?

#60

Post by samsquire »

stephenr wrote: post #42
samsquire wrote: post #12

I think documentation MUST have screenshots. I was recently trying to work out TLA+ in TLA Toolbox and there is there is this screenshot in the documentation on this page on PlusCal: https://www.learntla.com/core/pluscal.html The screenshot about going to File menu and clicking "Translate PlusCal Algorithm" was invaluable! Now I can learn that Ctrl+T is the shortcut to run the translation. EDIT: Before this point I w…

> 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 IntelliJ linting configuration to work" or how to set up all the IntelliJ modules or facets.

Someone coming in with no experience has to learn:

* git

* command line

* linux

* containers

* gradle (build runner)

* makefiles

* java jar files,

* pom.xml

* javascript bundlers, React/Angular, selenium, frontend testing, storybook

* database migrations

* IntellIJ' integrations/representations of the above

Post reply on HN