6 ms·
Should you add screenshots to documentation?
- artur_makly 3y agoLots of our enterprise customers use us just for this use-case and to keep tabs on visual / scope changes. https://VisualSitemaps.com https://VisualSitemaps.com
- paol 3y agoTarget 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.
- tristramb 3y agoThose 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.
- JumpCrisscross 3y ago> They treated everyone as if they didn't know how to use a menu This is most people in 1998.
- PeterisP 3y ago> 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.
- anigbrowl 3y agoNot 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.
- opportune 3y ago> 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.
- clementmas 3y agoI 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.
- brettermeier 3y agoI 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.
- hitchstory 3y agoFor 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 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.)
- triyambakam 3y agoExactly what I was hoping to find in the comments. Thank you
- ReactiveJelly 3y agoFor 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.
- Tempest1981 3y agoAre 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.
- deleted 3y ago[deleted]
- rightbyte 3y agoHolyC is the only one I know about ...
- mbork_pl 3y agoProbably 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...
- woodrowbarlow 3y agoyou 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/knuthweb.pdf http://literateprogramming.com/cweb_download.html http://literateprogramming.com/cweb_download.html http://literateprogramming.com/tools.html http://literateprogramming.com/tools.html
- Max-q 3y agoWhen 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.
- bingo-bongo 3y agoYes, 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.
- scooke 3y agoThis 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.
- ReactiveJelly 3y agoI 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.`
- PeterisP 3y agoI 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.
- mattjenner 3y agoSince 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?
- samsquire 3y agoI 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 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.
- Kwpolska 3y agoThis 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.
- stephenr 3y ago> 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.
- yread 3y agoIt's a complex tool with lots of hard to discover features. Training can be more efficient than watching youtubers use it since you can ask questions
- 3y ago
- CodeGroyper 3y agoYes, make a reference to a picture generated by opening puppeteer in your CI or CD pipeline when building prod.
- _8j50 3y agoI 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.
- pjc50 3y ago> 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)
- GuB-42 3y ago> 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.
- BoppreH 3y agoThat's a really insightful view. 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.
- DharmaPolice 3y agoYes 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.
- helsinkiandrew 3y ago> 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.
- d--b 3y ago> 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?
- rcxdude 3y agoIndeed. 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.
- scantron4 3y agoThis 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.
- Popeyes 3y agoIf 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.
- baby_souffle 3y agoExactly! 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.
- dsab 3y agoOf course yes! You should add examples of API use too. I hate how documentation without examples is dysfunctional - see example of CMake documentation.
- drewcoo 3y agoI 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.
- Cthulhu_ 3y agoOne 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.
- ulrischa 3y agoThere 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
- tairar 3y agoHonestly 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.
- phendrenad2 3y agoYes, but the real question is: should you have text in your documentation?
- mebazaa 3y agoI 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.
- blackoil 3y agoLong 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.
- jzombie 3y agoSlide 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.
- boxed 3y agoIn the iommi docs we don't have screenshots (except the intro demo video). We have iframes with the real HTML output of the tests! https://docs.iommi.rocks/en/latest/cookbook_tables.html 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.
- aaron695 3y ago[dead]
- eterevsky 3y agoAs 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.
- timojeajea 3y agoI built a screenshot API called ApiFlash. https://apiflash.com https://apiflash.com Quite a few of my clients use it to add "always up to date" screenshots to their documentation.
- zerojames 3y agoThe "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).
- bluenose69 3y agoI think screenshots are very helpful. They are much easier to follow than instructions like "look at the top-right of your screen; find the word just below the red box; click that; on the new screen, find ..." and so forth. As for going out of date, it helps to include caption with the date of screen capture and the version number of the software. My only problem with screenshots is that they sometimes show the whole screen, so the text is quite small. An exploded diagram (full view on left, with a box in it for the focus, and the focus view on the right) can help a lot. We who write manuals for software ought to take some hints from those who write manuals for car repair, etc.
- xenodium 3y agoI built a macOS commmand line util to take window screenshots or videos https://github.com/xenodium/macosrec https://github.com/xenodium/macosrec Window screenshots are mostly covered by macOS built-in app, but videos are not. Mostly grew out of a desire to post screenshots in my posts (https://xenodium.com https://xenodium.com) and projects (ie. https://github.com/xenodium/chatgpt-shell https://github.com/xenodium/chatgpt-shell). I often wish I could see how some projects look before I install them (but they often don't have screenshots). I'm doing my bit with my projects, I hope.
- jot 3y agoIt's not easy keeping screenshots up to date. One situation where you should always have screenshots in your documentation is when the documentation is for a screenshot API. We recently updated our docs to do a better job of this: https://www.urlbox.io/docs/options#url-examples https://www.urlbox.io/docs/options#url-examples
- shreelekhaaa 3y ago[dead]
- aurizon 3y agoscreen shots, and youtube 'shorts' with fat mouse pointers are assistive, especially if the learner has 2 screens for shadowing. It can also be done with dual windows for single screens. I have dual 34" screens and often have many panels, screens are so cheap these days. Dual phones also work on a smaller scale with secondary connectivity via WiFi and sim, etc
- Aachen 3y agoInteresting 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
- vkaku 3y agoYes. Because it'll help people understand Workflows when compatibility breaks. Just like it is good to document the bill of materials / runtimes required for running a system.
- billowycoat 3y agoThe Textual project has a lot of screenshots in its documentation. These screenshots are built with the docs, so they are always up to date. https://textual.textualize.io/ https://textual.textualize.io/
- rmoriz 3y agoWhen I was at school they told us people learn differently. Through examples, through listening to loud reading and by doing (e.g. applying things). I for one can learn fast through examples and visual representation. A wall of text can be very frustrating so I personally like screenshots when appropriate. I support the author's points, that screenshots must come with a description what or why something has to be done. Not just "click this and that and you will be done". I also strongly support the remarks about automation of screenshots. Outdated screenshots are the worst.
- roydivision 3y agoPlease, 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 for chat and email.
- thaumasiotes 3y ago> there are so many reasons not to do this > no copy/paste That would be a benefit of using screenshots, not a reason not to use them.
- roydivision 3y agoHow so?
- thaumasiotes 3y agoCopying and pasting seriously inhibits learning and tends to directly cause mistakes.
- crispyambulance 3y ago> Incidentally this also goes for chat and email. Oh hell no. I agree with your point for documentation, but when you're trying to communicate something quickly, it's helpful to take a screenshot, apply a red circle and an arrow to point to an issue AS YOU SEE IT in your context. It's fast, direct, and to the point. And if there's need for more info, that can be followed up with in plain or formatted text and/or attachments.
- tjpnz 3y agoThis is especially true of some programming blogs where instead of giving you the code they'll give you a screenshot of the code instead.
- opportune 3y agoI think a small source of confusion/varying opinions here is that this is from the perspective of a technical writer. Technical writers are usually producing documentation for external users (author mentions "customers") as their key deliverable. At least for me, I'm not too bothered by the docs I write looking a little unpolished or going out of date every now and then. Only a couple dozen people are likely to ever read it, it's not a big deal if I miss something because they'll know I wrote it and reach out directly if they need clarification, and as a corollary I'm mostly optimizing for "make it so explicit that they don't need to reach out for help, but not so verbose that they give up before reading it and reach out for help". Everyone knows it's a best-effort side task and you're not being held to a high standard - for guide-like documentation, just show the critical path most people care about and hope for the best. When I consume official external documentation though, screenshots are a smell, especially in the case of "[having a screenshot] For every step in a task." You can't just message the writer to ask for clarification if you deviate from the happy path. So documenting the user-journey with screenshots instead of the functionality no longer works, because you have no real escape hatch as a confused user.
- CM30 3y agoOf course, the visual reference can help clarify things that text alone can't explain. For example, take a simple task like 'fill in these fields in the config file'. For someone with software development experience, it's pretty obvious what the needed format might be there, whether it's a JSON file, PHP file or in any other language you can think of. But a new user might not know that. They might not know what's valid in a JSON structure, or that leaving out the quotes in a PHP variable's value will break things (especially if there's a space in the value they enter!) Pairing somewhat detailed text instructions with a screenshot or diagram can help avoid this, and make it obvious how the information should be provided. You could also use video footage along with the screenshots too if you have the time for it. It's a lot more work for sure, and I understand why most documentation creators don't do it, but it helps shows steps you might have forgotten while writing the docs, since it's very easy to leave info out or skip over things because they're like second nature to you. Honestly, all three formats being available is probably the ideal here, but having at least the screenshots will make things significantly easier to understand at least.
- fuzzfactor 3y ago>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.
- neverartful 3y agoIf I'm reading about something for the first time, screenshots are often helpful (and reassuring). On the other hand, if it's a fairly routine operational procedure that the reader should already be familiar with I find them troublesome.
- zbrozek 3y agoI crave screenshots especially when the UI is very complicated. Documentation that tells me to engage the encabulator is hard to use when I don't know what the icon looks like or where it is or if there's a menu entry or how deeply nested it is or how to get it to take input. There are tools which I use infrequently enough (e.g., GIMP, which I use about twice annually) that I don't really want to learn the tool. I want to get the job done and move on. Screenshots to help me navigate a UI, even if modestly outdated, are enormously helpful.
- stevenjgarner 3y agoYes
- squidbeak 3y agoThe article seems to miss one of the more important purposes of screenshots. They can compensate for weaknesses, points of confusion you may not realise exist in your docs, or any trouble with reading comprehension in your audience. At the very least, it's a courtesy to save your reader time.
- koinedad 3y agoUp-to-date screenshots usually make things faster if I’m new to the product (which is usually why I’m looking at the documentation). But I think it’s 100% difficult to keep updated. Happened to me recently at work. I had to some documentation I wrote with screenshots and we moved to a different tool for the same purpose. More work for me to update now
- thiht 3y agoYes. No exception. No « but ». No « considered harmful ». Always add screenshots. Even better, generate them automatically, I did that with an open source project and it was amazing.
- RajT88 3y agoDocumentation should have screenshots. Even more important - documentation should have examples of what valid parameter values are. Probably my biggest pet peeve in docs is describing what a param value should be, but leaving it up to you to figure out what that actually means. Sometimes there's a certain format expected, or several candidates for the parameter value. It drives me up the wall, that there can be very verbose documentation, and you still often don't get the parameters right on the first (or third) try. This article for example is doing it right: https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/cc990289(v=ws.11)#examples https://learn.microsoft.com/en-us/previous-versions/windows/...
- bbds 3y agooh yes, 100% agree. Few months back I was given link to a repository in which I needed to add a configuration file in yaml format. In repository readme first thing I saw was a screenshot of a text editor with possible yaml objects and properties and a text description for them, second was a paragraph of vague description on how the tool that consumes this repo works. No text on yaml structure in readme, no schema, no validation, nothing.
- politelemon 3y ago> Outdated screenshots can cause customers to lose trust in documentation accuracy. Do you have a source for this? I've not experienced similar feelings when looking at older outdated screenshots, but I do when finding incorrect instructions.
- freetonik 3y agoAnecdotal, but I do feel this when reading documentation for commercial products. I start to wonder, often unconsciously, whether the documentation is outdated (so, following it may lead to an error), or there isn't a good cooperation between designers and documentation writers (and the possibility that those are different people/teams doesn't feel too well, either), or the UI changes very rapidly (so I can expect possibly unwanted changes once I learn something).
- smore 3y agoThanks for reading! The source is my experience working in the industry and interacting with other technical writers and customer feedback submitted on doc pages, posted in Slack communities, and more. I've spent years reading comments from readers asking for updated documentation because it has a screenshot of a different UI than the one they use—even though the rest of the content is accurate. It's difficult to find published research about technical documentation because basically only Nielsen Norman Group is doing extensive research on web content. Baymard Institute, who I link to in the post, also does quite a bit of research but even more broadly and mostly on overall website and web marketing content.
- karaterobot 3y agoIf a screenshot isn't up to date, chances are the UI it depicts has changed as well, and the description of how to use the application is also out of date. I think it's an argument for not throwing documentation over a wall and never looking at it again, but rather including documentation updates as part of the requirements for a feature change. The accessibility objection seems very weak. Yes, if you don't make an image accessible, it's not going to be accessible, that's tautologically true. So, don't do that!
- stevefeinstein 3y agoScreen shots shouldn't replace good text documentation. The Doc should work find without it. But screenshots can help with comprehension. As for letting screenshots become outdated, if you are updating the rest of the doc, why wouldn't you update the screenshots at the same time?
- starkparker 3y agoGoing 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.
- deleted 3y ago[deleted]
- layer8 3y agoWhat we need is better tooling to recreate the requisite screenshots automatically for an updated version. This should in principle work in the same way that other parts of the documentation are auto-generated.
- buildsjets 3y agoYou should never, EVER use animated GIF screenshots of people typing in a CLI as your only source of documentation. Here's an egregious example that was posted yesterday: https://github.com/ofek/pyapp https://github.com/ofek/pyapp
- instagib 3y agoI 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.
- gorkish 3y agoOf course you should; what a stupid question. If you cant keep your docs up to date, what are you even doing? Something else is wrong.
- m1keil 3y agoI don't have issue with screenshots in docs except for one small caveat: too many screenshots. Don't screenshot Every. Single. Step. Doing so makes the documents harder to read as every paragraph ends up seperated by one or more screenshots. Make sure that "the point" of the screenshot is clear. If required, crop or highlight the important bits. Granted, screenshots will go out of date but so will any other documentation. This is also why having bit less screenshots will help you keeping docs up to date. If you still think that screenshoting every step is a better idea, consider screen recording instead.