Hacker News Reader

Comment by Max-q | Hacker News Reader

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 all the parameters listed up and brackets showing where to put it.

Start concrete, then go abstract when the basic knowledge is communicated successfully.

View on HN

I've brought this up before, and even though I don't use the service much anymore, I still love Airtable's API documentation - they customize the API calls for the table you're actually on, so instead of the generic example of "say you want to create a new CAR entry linked to the SEDAN category, with the RED color property", it pulls the names of fields/etc. to use in the examples from your actual table.

It's a small detail, but is still one of my favorite examples of making documentation more concrete.

I always appreciate it when documentation does this. Is there a technical term for this implementation?

I suggest "Contextual examples"

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.

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.

This is true... I still often don't know if instructions for entering data should include the "" or the <>...sometimes they seem to, often not. But seeing a screenshot would help.

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.

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.

I on the other hand am absolutely grateful for all the 'trivia' they throw in the manpages especially when trying to fix a problem withy system. It's the people that run into edge cases you want to help.

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.

Or, "Hey, that looks like Windows — does this even run on a Mac?"

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.

> Counter example: try painting “a primary and a secondary disk”

Primary and secondary are kind of abstract concepts though. I think you're restating the relationship a little differently.

> Counter example: try reproducing an image from a description.

we now know the impetus for generative AI! someone couldn't understand the docs, and built a tool for it

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.

> 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).

Also, reference docs are not the same thing as tutorial/learning docs. The two should complement each other, but the latter should really focus on gently bringing in people new to a product, technology, ecosystem, whatever.

Shouldn't need to be said, but from experience, it does.

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.

> Abstract thinking is good in the next step, when you already know the topic.

I honestly find the abstract perspective much more "approachable" (I really find it quite easy to learn highly abstract mathematics).

The issue rather is that very abstract texts have much higher quality demands on the writer - if you explain things badly, the reader will likely not understand. Similarly, much less (subtle) errors in the text are acceptable before the reader will be confused.

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

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.

Reply on news.ycombinator.com