so I'm reading through the Mac Plus manual, and I'm struck by how alien some of these concepts must have been.
They have multiple pages devoted to how to use a mouse.
On the other hand, the OS has a very consistent workflow and design language and methodology. They can explain complicated, abstract concepts in simple ways because they are consistent.
Apple of 1985 did a lot of things worth admiring (and a lot of shit, but that's another story.)
This kind of well produced, very well written, very thorough software manual, one that doesn't make assumptions about what knowledge you're bringing to the table, is sorely missing from modern software.
I'd pay $20-30 to have manuals like this for many pieces of modern software.
(OTOH, those pieces of software would need to be more well designed, and more consistent in their design language, in order for a manual like this to be at all useful.)
It's revealing of the state of the industry at large that software manuals don't exist anymore, and that documentation is often an afterthought.
It's elitist, IMO.
The books that I got with my Atari 400 (hand me downs in the mid nineties, I can't comment on what shipped with the system originally) were super thurrough, and also written at novices.
They didn't assume people knew about computers (because no one did) and they didn't assume people would just 'figure it out' (because no one would.)
I had all manner of books on computers when I was a kid, and very few of them were hard to understand, even as an 8 year old.
I had books from the 80s written at an elementary or middle school level that better explained complex computing concepts than the textbooks I had to study in college.
I'm not kidding. I lead a study group, because I was basically sleeping through the classes and some of my friends were struggling. So I lead a study group to help out.
I brought in these books I had read when I was a kid, xeroxed off copies of the relevant illustrations and explanations for everyone.
The effect this had on the average grades in the class was so pronounced that my teacher asked me what I had done.
I brought him the same books, and he looked shocked.
You know that slightly wistful, vaguely watery look people get in their eyes when something they care about is done really well, but in a way that makes a lot of effort they expend useless?
It was that. He started hunting down vintage copies online, and incorporating them in to his lectures.
And, like, I get that I was a weird kid. I read reference books and maps and stuff for fun.
But I struggled through the bland and boring books because I'd seen how useful reference books could be, and I'd learned that mostly through these very thoughtful books on computers.
When I get settled in to the new house, I'll pull out those books and take some pictures. I imagine many of them are on Archive.org already.
We, you and I, have a chance to fix this. We, you and I, can rebuild and repair.
- Make user friendly (not user hostile) devices and software
- Write documentation
- Refuse to buy tech that *we* can render safe to use, but that the average user can't
- Support people that do things correctly financially whenever possible.
We can 'vote with our dollar'
We can write to our congresscritters about the DMCA (a law that is wielded by the likes of Lexmark and John Deere and Microsoft to keep their devices user hostile by rendering it illegal to install your own software.)
We can normalize the idea that reading documentation is sometimes required, and in the process, help folks bridge the gap in computer literacy.
I own several kindles, for example. I've bought them all used, so I don't feel bad about owning them, but I wouldn't buy one new.
I purchase cheap used android devices, root them, and give them to friends in need. I write documentation. I build dumb simple scripts to automate common computer tasks for people that need to perform those tasks, and only those tasks, and are uninterested in performing any other tasks.
And yeah, part of this goes back to #deletefacebook
Facebook is user hostile.
But it's larger than that.
Modern Windows, MacOS, and even Ubuntu have some user hostile behaviors baked in.
And in the FOSS world the only real successful business model has been "give away the software, sell the support" which means that their is an incentive in FOSS to keep the documentation technical and complicated.
RTFM culture is user hostile behavior.
Corey Doctorow frequently slips bits about writing the documentation in to his fiction that involves programming.
He's normalizing the idea that documentation is important, and empowering (and that, in contrast, a lack of documentation can be seen as oppressive.)
@ajroach42 however good thread however I disagree a bit because just looking at the fundamental protocol of Internet you can see that they weren't designed with security in mind. It's also true that they didn't thought that it was going to be a vital infrastructure like it's today.
That's probably part of it. There probably was a time when reading the documentation was enough to answer most common questions.
But we kept that part of the culture, and lost the part of the culture that thoroughly and clearly documented its software.
And I genuinely believe that the FOSS business model of giving away the software while selling the support has a lot to do with it.
> just read the code to determine what the software does
Those people have clearly forgotten or chosen to ignore the wisdom of Donald Knuth: “Beware of bugs in the following code: I have only proven it correct, not attempted to run it”
(Not to mention that the relevant code is often in some non-obvious place in the source files)
IMO, there's a place for telling people to read the code, but that's when they're interested in low-level details and either already know the overall design of the codebase, or you point them to the relevant file.
But for understanding the big picture, it's valuable to have the architecture summarized, preferably with pictures.
Part of what I'm doing with Collab is trying to answer the question, "Is it possible to create a social network that's not evil?"
What I like about Mastodon is I find some good people and share with them. I'm not getting anything shoved down my throat.
Facebook, YouTube, Twitter, etc. are all about pissing everybody off. What's wrong with having some nice conversations, making something, and enjoying yourself?
@ajroach42 full disclosure: i have an "RTFM" sticker on my laptop and probably always will, a bit of a totem from an earlier situation in life and also because it remains good _advice_, as far as it goes, though a bad way to interact with people.
but i pretty much agree with this. especially in an age when everyone refuses to actually WTFM.
The thing is, making the sort of high-quality documentation you mention is hard and expensive.
Old computers had such good manuals because they were expensive luxuries and the makers needed to justify the purchase. A good manual meant a user who felt like they got their money's worth.
These days, PCs are cheap typewriters. The good (and bad) manuals out there are being sold as how-to books.
(There's also the pernicious GUI == easy-to-use meme, but I'm out of chars.)
@suetanvil totally agree.
Expecting FOSS software to provide the same level of documentation that these older commercial software were able to provide is unreasonable, unless we’re willing to support them financially or with labor to do so.
And a lot of modern commercial software is also distributed ‘for free’ with little incentive to invest in documentation.
The race for more features and bigger and faster computing devices may have blinded us to the human-centric usability successes. Since it will all be erased in 3 months because "break things fail fast," how cruel to ask for thoughtful documentation to be written.
@ajroach42 @suetanvil Documentation doesn't make money. Most customers will not bother to read it anyhow because of the distracted culture we live in -- distracted because of the computer-centric competition for our attention ("eyeballs"). It's a vicious cycle --reinforcing negative loop-- that we must break out of by nourishing the balancing loops.
@ajroach42 I agree with most of your points. But some of it is just evolution. Car aficionados will say the same thing about being able to work on their car engines. Nobody knows how to change their own oil. Most people can’t. Cars don’t work that way any more. For many, that’s a GOOD thing. People today start at a different point in evolution. They don’t have to evolve from where we evolved from. Standing on the *shoulders* of giants and all that.
@ajroach42 For some reason, as a dev, documentation is viewed as second-class work. We're instructed that it's somehow beneath us to have to worry about that. That should be someone else's job.
Hell, at Canonical, we even brought on some tech writers for documentation on Ubuntu and other projects, because it wasn't the dev's responsibility. When the vast majority were let go during layoffs, we never re-hired, but neither did we do much to increase our documentation efforts.
@ajroach42 I mostly agree with that, however there are some instances of "community supported" business models. Like (wait for it) Mastodon.
I think the problem is also partially on the side of users -- we're all so deeply conditioned to not pay for stuff unless we have to that it's hard for community-driven projects to get enough monetary support from the community itself.
This has to change, and is slowly changing. Which is good.
Point is, it's not just on the projects, but on all of us.
@ajroach42 in other words: we need to learn to financially support projects that are important to us even if they have no way of twisting our arm to make us pay.
That way they will not have to twist our arm to get enough financial support to survive and thrive.
We're all in this together.
I'm a very happy user of elementary OS which has gotten some undeserved flack for pushing this change. And my father is involved in a push for Australia/NZ to adopt a policy of paying for the Free Software we use, and I think we kiwis are in a good position for this. Afterall our indigenous people have a term for this, "koha".
@mangeurdenuage I think I cover that pretty well in the thread.
And, frankly, there's no polite way to say "read the fucking manual."
I'm advocating for better, and more user focused documentation. The fact that our default response to questions is "Read The Fucking Manual" is a cultural problem.
@ajroach42 Imo, as well, it's because writing documentation is a skill. It's not easy to do without at least some basic instruction or training.
It's similar to what I've run into while looking for tutorials on various things online. There's a lot of people out there who seem to find it hard to write down a process in a way that a novice can understand.
The people who are good at writing it down are either themselves beginners, or have been making tutorials for a while.
@ajroach42 It can also be harder for more technical users of the creators of a thing to document it in a novice-friendly way - but that's what technical writers are for.
But from what I've heard, having a permanent (even part-time) person or team on staff to handle documentation is extremely rare these days. I'd wager most technical writers are freelancers or on short-term contracts.
@dartigen In my org, I do most of our technical writing.
I'm a support engineer. I don't have time to write documentation.
so our documentation ends up being FAQs, you know? When someone asks a question, or has a problem, I answer it as thoroughly as I can, and that becomes our documentation.
@ajroach42 And that's better than nothing, but I bet it has nothing on those vintage manuals. Based on my SO's experiences (he's in a similar position, and with similar issues with documentation) that's pretty common in the tech industry, and a big part of the problem.
Someone trying to do a different job doesn't have the time to write good documentation.
I'm not sure why permanent technical writers are so rare, but I'm guessing it's because orgs think they don't need them.
@ajroach42 alternatively, the easy-provided hosting while still doing RTFM is actually a good model. Look at Social.coop - you pay to use their Mastodon instance while they handle the technical expertise. Same reason WordPress is successful same reason Rocket.Chat will be. The ones that don't succeed don't provide an easy solution for laymen. It should be apart of the business model; if you're offering your product, offer a one-click solution for a price. But yeah, support to use...
@acaiSG Either I am misunderstanding what you are trying to say, or the behavior your describing is what I am actively advocating against.
If you're making your product more complicated than it needs to be in order to sell your services, you're doing the community and your users a disservice.
Social Coop//Mastodon is an edge case in that the software is necessarily complex and still evolving, and it is run by a community.
Wordpress achieved dominance with a one click installer *and* good, strong documentation and community support.
Wordpress is a holdover from the last era of not actively user hostile software, but even it isn't perfect.
I disagree. I wouldn't say that a lot of FOSS projects have only technical docs.
UX is not always perfect, agreed, and documentation needs improvements, if it even exists, but I wouldn't say they are kept technical by intention.
There is a point in tech where some technical knowledge is mandatory to make a useful decision.
And many people don't read documentations, no matter how go they are. That's why we have communities for helping people.
As for me, I really try to write documentation for my apps. But I put so much into keeping it consistant with the OS and providing inline help, I'm not really sure what to document or how to structure it.
Nevertheless I do get something out.