Live data from Hacker News

Should you add screenshots to documentation?

thisisimportant.net

111–120 of 127 posts

Re: Should you add screenshots to documentation?

#111
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.

> They treated everyone as if they didn't know how to use a menu.

Yes, and that's OK - somebody had to do it for hundreds of millions of people!

My own first summer job long, long ago as a student was helping a small company transfer some paper "business processes" and calculations to Excel, and that involved teaching Excel to a few people double and triple my age. They generally had few issues with Excel itself, as they had worked with paper spreadsheets in pre-computer accounting, but a significant challenge was mouse skills, because as it turns out, if you move the pointer where you want to, lift your hand up, and press the mouse button, then as you press the pointer will slide away from where you wanted to click.. so that took some time and practice.

Don't take things for granted. People weren't born knowing how to use a mouse or other tools. Everything that's universal now had to be painstakingly learned once, and yes, these materials did have to teach people how to use a menu, because that was relevant for much of their target audience.

Re: Should you add screenshots to documentation?

#112

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.

I find myself craving examples for _everything_ even as someone experienced with a variety of tools. So much documentation for APIs, CLI programs, _everything_ is painfully lacking in examples. Or the examples will be just totally wrong or out of date, then search engines and LLMs slurp it up and give you bullshit examples when prompted. So now a lot of my comments start with `// e.g.`

I agree that it's the usual case, but on the other hand, right now I got quite frustrated with a project because the manufacturer has only provided examples and tutorials and there is literally no reference material - which was fine when I was starting out, but horrible for debugging where I'd really need just a few sentences describing how exactly that call works and I'd want an exhaustive list of what my other configuration options are there and what they do, not an example of doing something close to but not exactly what I need.

Re: Should you add screenshots to documentation?

#113
Going to bang my drum again that screenshot automation and fears about outdated screenshots are _very very very_ good reasons why your org's technical writers should be best friends with whoever's writing the product's tests, and also that every documented assertion should be reflected in a test.

Re: Should you add screenshots to documentation?

#117
I complete documentation as if I’ll be hit by a bus / win the lotto / retire soon. Then someone between the secretary and an engineer will have to pickup the pieces.

I have routinely had people stop me in the hall to tell me thanks for the tutorial I wrote. As a negative, new test data was created and I saw ten people trying to use up resources to process the data.

Yes, screen shots, possible error messages, work-arounds, and anything else someone cares to maintain.

Re: Should you add screenshots to documentation?

#118
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…

There is a deeper problem here: what is concrete in a UX?

Most software design has a rigidly defined UI. That means that the most concrete aspect of the UX is what the user is looking at.

But does this have to be true? Is it really a good idea? I don't think so.

---

A UI that always looks the same is inflexible. This has advantages and disadvantages:

Pros:

* The UI won't surprise the user. The user can predict where to go next, because the layout never changes.

* The UX is optimized for a "happy path".

Cons:

* The UI will never accommodate the user. The user cannot move superfluous UI bits out of their way. The user must always contend with the entire app all-at-once.

* Any flow that is not the "happy path" becomes a maze at its best, and a fortress at its worst. The user's ability to introduce novel UX behavior is either minimized or outright banned.

---

We are approaching this subject with what we are used to: GUI. Let's take a step back in time, and think about text user interfaces (TUI). Let's think about shells.

What is concrete in a shell's UX? Not what you look at, that's for sure! Not the behavior, either! Hell, even the environment is flexible! Is there anything concrete?

The abstraction. That's the stable part. Shells have environment variables, stdin, stdout, stderr, signals, pipes, etc. We can't predict what will use these abstractions; but we can predict that whatever it is, it will use them.

So how does a user learn to use a shell? They learn the abstract thinking first! Pretty convenient, isn't it? Sure, there is a high upfront cost, but that only needs to be paid once.

The pros and cons are essentially the opposite as above.

Re: Should you add screenshots to documentation?

#120

Earlier quoted context omitted.

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.

> They treated everyone as if they didn't know how to use a menu. Yes, and that's OK - somebody had to do it for hundreds of millions of people! My own first summer job long, long ago as a student was helping a small company transfer some paper "business processes" and calculations to Excel, and that involved teaching Excel to a few people double and triple my age. They generally had few issues with Excel itself, as…

Not exactly. 'Cash in' books like this don't just teach you how to use a menu once, they teach 100 times to pad the size of the book. I am absolutely in favor of screenshots, but if they become massively dumplicative then the reader never gets past entry level.

A lot of publishers choose quantity over quality. One publisher that aims at developers uses a large font so the books look thick but the subject matter is not that details and you just end up endlessly flipping pages because the word count per page is so low.

Post reply on HN