Live data from Hacker News

Should you add screenshots to documentation?

thisisimportant.net

81–90 of 127 posts

Re: Should you add screenshots to documentation?

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

Re: Should you add screenshots to documentation?

#82

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…

For those who want to do it manually, just give every screenshot a number, and put comments in the code saying "This UI layout / function affects Figures 1, 2, 4, 7". If you don't trust your team to maintain a sequence (fair) use random numbers.

This also helps when people want to refer to a particular screenshot, and it can double as anchor IDs in an HTML page.

Re: Should you add screenshots to documentation?

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

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.

Re: Should you add screenshots to documentation?

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

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.

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/

Re: Should you add screenshots to documentation?

#85
post #18

> Outdated screenshots can cause customers to lose trust in documentation accuracy. as opposed to outdated documentation without screenshots, where the user has no idea that he's reading stuff from 5 years ago?

Exactly!

Even with old screenshots, you can still see what your next action is supposed to be and what functions were near it. That’s invaluable for trying to find the function you need in a new UI.

I can give you a guide for how to do just about anything using screenshots of the AWS console from years ago and you probably wouldn’t have that tough of a time adapting them to the current UI.

Re: Should you add screenshots to documentation?

#86
>Identify the purpose of a screenshot

The author emphasizes this as one of the important considerations.

Definitely a good idea but I think people need to go further.

I would say identify the purpose of the document to start with.

Ideally, I would like to have a complete reference tome where the text could actually stand on its own extremely well if it had to, along with detailed essential illustrations such as charts or schematics. Any other drawings or screenshots should serve as the icing on the cake without actually being essential to understand the documentation.

If lots of illustrations are intended to be mixed with the final text anyway, this type of document can still ideally be drafted and revised in text only format, quickly leaving placeholders for future illustrations as you go along. All you need at this point is a pretty good idea of what kind of picture you would put there after you are done. You'll also have more time later to think about the exact ilustration you'll want for each placeholder, and better able to select or create more meaningful pictures the first time. Once the final draft of the text is complete, then (only) the most helpful illustrations can be introduced to their expected positions. Then without (much) further editing to the text, consider the initial placement of illustrations to be a first draft of artwork, then it may only be necessary to manipulate the artwork alone a little bit more before a final draft of that complete document is reached.

I think reference documentation should be complete and text-heavy.

If there is actually no real reference documentation, then whatever is documented will need to be more text-heavy to compensate.

OTOH the the heavily-illustrated approach should be reserved for more specific topics such as detailed tutorials or quick-start guides.

Different documents having different purposes, compiled into a full documentaton package.

Re: Should you add screenshots to documentation?

#87

Are there tools/IDEs where you can attach screenshots or sketches to code (source files)? More integrated than a README with images, ideally. I understand the out-of-date concern... still interested in how it might work. Feels like something that probably existed in the 90s as part of some bespoke ecosystem.

you might be interested in "literate programming", a technique pioneered by Donald Knuth. the idea is to write your code in steps, inserting notes and documentation into each step. you can then use tools to "weave" (produce documentation) or "tangle" (produce runnable code).

note: to do this properly, it should involve more than just inserting notes into your code. you'll need to adapt the way you write and design your code too (for adding documentation to various intermediate states, rather than just the way it looks right now).

http://literateprogramming.com/knuthweb.pdf

http://literateprogramming.com/cweb_download.html

http://literateprogramming.com/tools.html

Re: Should you add screenshots to documentation?

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

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.

Re: Should you add screenshots to documentation?

#89

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…

This is especially true of some programming blogs where instead of giving you the code they'll give you a screenshot of the code instead.
Post reply on HN