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 wasn't written so much as screenshoted. And I realized this made perfect sense - a non-technical audience needs to be hand-held through every step, and a GUI application is inherently visual not textual, so a text-based guide would just be harder to follow.
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.
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.
> Target audience is a big factor too, I think the article failed to emphasize this. And, secondly, the nature of what is being documented.
Right, I'd say screenshots are crucial for certain kinds of documentation and terribly amateurish for others. A guide walking you through a user journey in a UI should definitely have screenshots.
But there should be "real" documentation for things like APIs - if the only kind of documentation that exists for an API is guides with screenshots, you end up with a bunch of useless "hello world + a feature" documentation that doesn't help you understand the big picture, or how features/options interact.
I think having at least one screenshot per feature can be very useful in some cases. I don't need step by step screenshots but I like to get a quick visual of what I'm trying to build.
I think so too. Screenshots help a lot, even if it's simple things as "where is the damn button?". To avoid screenshots completely is often a bad idea.
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:
(the website example has screenshots generated by playwright, the REST API example has real tested JSON snippets, the command line example has command outputs, etc.)
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.
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.
Probably not what you have in mind, but Org-mode can do it (more or less). And if there's a place this is implemented already (or will be soon), I would bet on DrRacket.
Still, an interesting idea. I'm more of a text guy than a visual learner, but I agree that comments in the form of images could be very useful. The problem I can envision with this is that whoever adds such a feature to some IDE/environment would probably run with it and add sound and video comments, too, and then it will be like XML: making sense in theory, but horribly abused 99% of the time...
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).
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.
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 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.
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.
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).
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 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.
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.
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.
> 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'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 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/
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.
Since I saw 'walkme' many years ago I became a convert of the tour concept. I now use the o/s versions in javascript. Not based on research, but I find walking tours, ones that live inside the platform giving a 'learn by doing' experience can be an immersive, contextual hands on way to learn. They only fall out of date if you ignore them during product changes.
Of course, some users, and at some level, we all want the hard docs. This is where you're moving down the engagement funnel, from orientation to the deepest murk!
I saw just yesterday 'is there a printable version of the docs so I can read them offline?'. A fair, but rare, request to make a point - don't cater for everyone's _preferences_ - that is risky.
It's a balance - but one I think if you need a screenshot to explain it, you should also consider how much it needed explaining. Is it work a screenshot, or a UX review?
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 was trying to work out why my code was not updating. I had no idea I had to do this important step! I didn't follow a tutorial, I just used learntla.com and the documentation is spread across multiple pages, so it's not obvious what text is important.
Some software is by its nature complicated and hard to understand. Such as IntellIJ or TLA+.
If you didn't have any training in IntelliJ, could you work out how modules work in IntelliJ? How gradle interacts with IntelliJ?
If you have a personal sideproject, I recommend you take screenshots to document milestones and progress and archive them on GitHub or somewhere. When the code stops working or building then you at least have some artifact that preserves what you did.
This specific screenshot seems unhelpful to me. The text below the screenshot already tells you the keyboard shortcut, it could also say "File > Translate PlusCal Algorithm" and be more accessible.
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.
That isn't really saying much. "Watching YouTubers" doesn't really seem like a way to learn how to do something, it seems like a way to waste some time and pretend you're one of the cool kids.
I can't be the only person who remembers when people learnt how to use a program by using it?
"Using it" is fine for a simple tool. But IDE is a complex beast. You can easily fall into a local optimum without discovering and using the best features. Think using arrow keys to navigate in vim. It works, gets the job done but is far from optimal. You could read the manual but I'm sure you agree that training is a lot more efficient use of your time
I mean you can poke around and read the manual/watch YouTube videos and discover things, or you could just have an expert in the thing interactively teach you how to use the program and its features. It's not about needing training, it's about optimizing time spent learning an advanced tool and all its features.
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:
I don't use IDEA for Java work, I use it because it's the only IntelliJ platform app that supports "all" languages (or at least all the languages I care about), but sure let's go with your examples above.
If you're hiring someone to do java work, who has no experience of jar files, or java build tools, them not being able to use IDEA is the least of your concern.
This is like saying "on the first day of work as a carpenter, we send all new hires on an intensive nail-gun training course, because they probably don't know how to use a circular saw, or even what the pointy end of a nail is for"
I don't know what schools teach these days, but all the classes I had (one of which, coincidentally enough was java) specifically made us not use an IDE - we had to use a text editor for all practical work.
Once you know what you actually need/want to do, using a different tool to achieve it is generally not a complex task.
If someone knows how to use a screw driver, they don't need comprehensive training to then use an electric drill/driver to put a screw in.
If they don't know how to use a screw driver, giving them a drill/driver to learn, is a fucking terrible idea.
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 imposes a distinct maintenance burden.
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:
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.
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.
My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox".
It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal.
I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is SO obvious that there was a missing step required in my mental model of how TLA+ works.
A beginner to IntellIJ needs to be taught that the "Play button" is what they're looking for, and a screenshot puts that into context.
Blender is a complicated piece of software, if you had text based descriptions of that tool - I wonder how useful that would be to understanding where similar functionality is placed. Compared to a screenshot WITH CONTEXT.
My case highlights how even what seems like a trivial screenshot can actually help people contextualise something that is basic to you.
Do basic features go in context menus, toolbars, or hidden in menus.
The text "Go to File -> Translate TLA+ algorithm" would be missed if it was in a big document in the middle, as if it's just a fact.
The screenshot says "This is important, pay attention".
> We discussed how to translate the pluscal in Setup, but as a refresher, it’s File → Translate PlusCal Algorithm in the menu (Ctrl+T/⌘T by keyboard). This puts a translation below the comment block:
Also, if it’s an easily-missed step and something just mysteriously doesn’t work if you miss it out, that’s not a documentation bug, that’s a design bug. (I’m not familiar with it.)
I think the discussion is caused by different implicit understanding of what "documentation" means. Different types of documentation have different, conflicting needs; an amazing reference document is a horrible tutorial and an amazing tutorial is horrible for reference purposes. So you shouldn't try to make your reference material be useful as a tutorial, that way lies madness, make a separate document if you need one.
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.
I was just yesterday reading docs from a project thag did this right. Most things are text but some pages contain a lot of screenshot because it involved Azure's complex settings that have simliar and confusing names. Screenshots shouldn't be the default but if they clear up confusing settings/UX they're very useful.
> 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-pressure against unnecessary UI changes.
I think screenshots are good. Sometimes essential, in a crowded UI what you want is a nice screenshot with a huge red arrow saying "this control here". The animated screenshots used by e.g. VSCode are even better.
And there's a secondary market for youtube content for really visual users which shows the UI actually in operation, all the transitions, etc.
(Not discussed: localization. This multiplies up the work, but in some cases e.g. CJK vs Latin or RTL languages, the screenshots may look significantly different. Oh, and if you have an accessibility mode for e.g. red-green colourblind, might be nice to show that in action as well)
> 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.
Perhaps one can extend it to automated UI tests too: if it breaks a test by moving an element/adding a popup/changing the flow/taking longer, then it would probably undermine existing users' expertise. What used to be a fragile test is now the canary in the coal mine.
Yes you should, but you need to keep in mind that's something you need to update every time you change something in your interface. It is incredibly frustrating when screenshots don't match what you see on screen, especially if you're a new user (i.e. the key audience for documentation). There's a horrible sense of doubt whether you're doing things correctly.
Probably another reason why you shouldn't change your GUI that often.
> 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.
But outdated documentation that describes how to do something in text that's changed is also infuriating to users.
A screenshot helps both users and future documentation maintainers determine if the instructions are out of date.
Indeed. I lose a lot more trust when I've spent 15 minutes trying to find the damn option the documentation insists should be there, only to find it doesn't exist any more. A screenshot at least gives me that information faster.
This is what I was going to say. Nothing more frustrating than trying to find an option that has been moved somewhere else (why is android documentation the worst about this). At least with a screenshot you know it is either where they say it is or that you need to find a different tutorial.
If you are writing documentation you should put a date on your content and a version number if it relates to a product.
I've been reading about accordions because I want to refresh a UI, but I read a document about the <details> element and accessibility and didn't realise it was from 2019 until I got to the end and saw the comments were all from that year.
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.
Of course yes! You should add examples of API use too. I hate how documentation without examples is dysfunctional - see example of CMake documentation.
I don't care about screenshots. I can still quickly skim past them.
But please do not force me to watch a video. Video-only documentation is the worst thing since advertising - total PITA to watch and keeps me from my goal.
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.
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
Honestly I think you're getting closer to the core of the problem than most. Appealing to multiple different learning styles is a fantastic idea. I see tons of people online talking about learning by watching Youtube videos... this doesn't work for me, but it's obviously helpful for a lot of them. Some work well with text. I personally have a great measure of success when I'm presented with playgrounds for learning, like the GraphQL docs which let you live edit the queries in the documentation to play with them and see how the concepts work. None of these is any better than the others and all should be considered for the highest quality documentation.
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.
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.
This is WAY better imo. It's just html, so works better on mobile. It doesn't have issues with different screen resolutions, and it also has none of the problems with accessibility. It's just HTML.
As a user I would rather have an explanation of how something works, rather than screenshots pointing to things that I need to click. Building a mental model of the software makes using it easier in the long term.
The "Intentionally add images to your documentation" heading in the article summarizes my position on this topic well.
Screenshots can be a useful learning aid. For example, if you are guiding someone through a complex product action which involves several steps, a series of screenshots can be helpful.
If you are writing a tutorial, having a screenshot of output (i.e. a web page, an image, a UI) is useful for readers so they can visually match what they have to the result you have. (This is not applicable for text-only outputs).
126 comments
[ 2.9 ms ] story [ 95.4 ms ] threadDo 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 wasn't written so much as screenshoted. And I realized this made perfect sense - a non-technical audience needs to be hand-held through every step, and a GUI application is inherently visual not textual, so a text-based guide would just be harder to follow.
Things are often the way they are because that way is easier to produce, not because it is useful.
This is most people in 1998.
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.
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.
Right, I'd say screenshots are crucial for certain kinds of documentation and terribly amateurish for others. A guide walking you through a user journey in a UI should definitely have screenshots.
But there should be "real" documentation for things like APIs - if the only kind of documentation that exists for an API is guides with screenshots, you end up with a bunch of useless "hello world + a feature" documentation that doesn't help you understand the big picture, or how features/options interact.
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, etc.)
This also helps when people want to refer to a particular screenshot, and it can double as anchor IDs in an HTML page.
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.
Still, an interesting idea. I'm more of a text guy than a visual learner, but I agree that comments in the form of images could be very useful. The problem I can envision with this is that whoever adds such a feature to some IDE/environment would probably run with it and add sound and video comments, too, and then it will be like XML: making sense in theory, but horribly abused 99% of the time...
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
> I chose the name WEB partly because it was one of the few three-letter words of English that hadn't already been applied to computers.
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.
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.`
[0] http://cheat.sh/
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.
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.
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.
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).
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.
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.
Primary and secondary are kind of abstract concepts though. I think you're restating the relationship a little differently.
we now know the impetus for generative AI! someone couldn't understand the docs, and built a tool for it
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.
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.
It's a small detail, but is still one of my favorite examples of making documentation more concrete.
It’s documentation but with only examples.
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.
Of course, some users, and at some level, we all want the hard docs. This is where you're moving down the engagement funnel, from orientation to the deepest murk!
I saw just yesterday 'is there a printable version of the docs so I can read them offline?'. A fair, but rare, request to make a point - don't cater for everyone's _preferences_ - that is risky.
It's a balance - but one I think if you need a screenshot to explain it, you should also consider how much it needed explaining. Is it work a screenshot, or a UX review?
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 was trying to work out why my code was not updating. I had no idea I had to do this important step! I didn't follow a tutorial, I just used learntla.com and the documentation is spread across multiple pages, so it's not obvious what text is important.
Some software is by its nature complicated and hard to understand. Such as IntellIJ or TLA+.
If you didn't have any training in IntelliJ, could you work out how modules work in IntelliJ? How gradle interacts with IntelliJ?
If you have a personal sideproject, I recommend you take screenshots to document milestones and progress and archive them on GitHub or somewhere. When the code stops working or building then you at least have some artifact that preserves what you did.
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.
That isn't really saying much. "Watching YouTubers" doesn't really seem like a way to learn how to do something, it seems like a way to waste some time and pretend you're one of the cool kids.
I can't be the only person who remembers when people learnt how to use a program by using it?
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
If you're hiring someone to do java work, who has no experience of jar files, or java build tools, them not being able to use IDEA is the least of your concern.
This is like saying "on the first day of work as a carpenter, we send all new hires on an intensive nail-gun training course, because they probably don't know how to use a circular saw, or even what the pointy end of a nail is for"
I don't know what schools teach these days, but all the classes I had (one of which, coincidentally enough was java) specifically made us not use an IDE - we had to use a text editor for all practical work.
Once you know what you actually need/want to do, using a different tool to achieve it is generally not a complex task.
If someone knows how to use a screw driver, they don't need comprehensive training to then use an electric drill/driver to put a screw in.
If they don't know how to use a screw driver, giving them a drill/driver to learn, is a fucking terrible idea.
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 imposes a distinct maintenance burden.
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.
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.
My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox".
It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal.
I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is SO obvious that there was a missing step required in my mental model of how TLA+ works.
A beginner to IntellIJ needs to be taught that the "Play button" is what they're looking for, and a screenshot puts that into context.
Blender is a complicated piece of software, if you had text based descriptions of that tool - I wonder how useful that would be to understanding where similar functionality is placed. Compared to a screenshot WITH CONTEXT.
My case highlights how even what seems like a trivial screenshot can actually help people contextualise something that is basic to you.
Do basic features go in context menus, toolbars, or hidden in menus.
The text "Go to File -> Translate TLA+ algorithm" would be missed if it was in a big document in the middle, as if it's just a fact.
The screenshot says "This is important, pay attention".
> We discussed how to translate the pluscal in Setup, but as a refresher, it’s File → Translate PlusCal Algorithm in the menu (Ctrl+T/⌘T by keyboard). This puts a translation below the comment block:
Also, if it’s an easily-missed step and something just mysteriously doesn’t work if you miss it out, that’s not a documentation bug, that’s a design bug. (I’m not familiar with it.)
This is an interesting overview of these concepts - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
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-pressure against unnecessary UI changes.
I think screenshots are good. Sometimes essential, in a crowded UI what you want is a nice screenshot with a huge red arrow saying "this control here". The animated screenshots used by e.g. VSCode are even better.
And there's a secondary market for youtube content for really visual users which shows the UI actually in operation, all the transitions, etc.
(Not discussed: localization. This multiplies up the work, but in some cases e.g. CJK vs Latin or RTL languages, the screenshots may look significantly different. Oh, and if you have an accessibility mode for e.g. red-green colourblind, might be nice to show that in action as well)
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.
Perhaps one can extend it to automated UI tests too: if it breaks a test by moving an element/adding a popup/changing the flow/taking longer, then it would probably undermine existing users' expertise. What used to be a fragile test is now the canary in the coal mine.
Probably another reason why you shouldn't change your GUI that often.
But outdated documentation that describes how to do something in text that's changed is also infuriating to users.
A screenshot helps both users and future documentation maintainers determine if the instructions are out of date.
as opposed to outdated documentation without screenshots, where the user has no idea that he's reading stuff from 5 years ago?
I've been reading about accordions because I want to refresh a UI, but I read a document about the <details> element and accessibility and didn't realise it was from 2019 until I got to the end and saw the comments were all from that year.
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.
But please do not force me to watch a video. Video-only documentation is the worst thing since advertising - total PITA to watch and keeps me from my goal.
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.
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.
https://docs.iommi.rocks/en/latest/cookbook_tables.html
This is WAY better imo. It's just html, so works better on mobile. It doesn't have issues with different screen resolutions, and it also has none of the problems with accessibility. It's just HTML.
https://apiflash.com
Quite a few of my clients use it to add "always up to date" screenshots to their documentation.
Screenshots can be a useful learning aid. For example, if you are guiding someone through a complex product action which involves several steps, a series of screenshots can be helpful.
If you are writing a tutorial, having a screenshot of output (i.e. a web page, an image, a UI) is useful for readers so they can visually match what they have to the result you have. (This is not applicable for text-only outputs).