Should you add screenshots to documentation?
thisisimportant.net
Should you add screenshots to documentation?
1–10 of 127 posts
Re: Should you add screenshots to documentation?
#2Target 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.
Re: Should you add screenshots to documentation?
#3I 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.
Re: Should you add screenshots to documentation?
#4For those interested in the concept of having guaranteed/permanently up-to-date documentation (with or without screenshots) I built this testing framework based upon autogenerating good how-to or reference docs from tests:
https://github.com/hitchdev/hitchstory
(the website example has screenshots generated by playwright, the REST API example has real tested JSON snippets, the command line example has command outputs, etc.)
Re: Should you add screenshots to documentation?
#5Are 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.
Re: Should you add screenshots to documentation?
#6Are 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]
Re: Should you add screenshots to documentation?
#7I 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.
Re: Should you add screenshots to documentation?
#8Are 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.
HolyC is the only one I know about ...
Re: Should you add screenshots to documentation?
#9When 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.
Re: Should you add screenshots to documentation?
#10Are 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...