4 ms·

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

by paol 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. 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 ago
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.
- 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 ago
    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.
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.

by paol 3y ago

tristramb 3y ago

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.

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 ago
  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.

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.