31–40 of 127 posts
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.
> 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?
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…
Quite a few of my clients use it to add "always up to date" screenshots to their documentation.
I 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 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 w…
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 wa…
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.
This is most people in 1998.
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).
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.