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.
My point is (and has been, for weeks) that we are ignoring the users.
We used to care about users. We wanted users to adopt hardware and software. We wanted users to be productive and secure.
Vendors cared about the user experience.
Now, everything is user hostile. Everything is trying to screw you, or spy on you, or just isn't engineered with your safety in mind.
We, you and I, have a chance to fix this. We, you and I, can rebuild and repair.
We can:
- 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.
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 - This is a great writeup. Thank you for it!
@ajroach42 once I heard that Arch Linux is an huge collective documentation project. However I am an Ubuntu user. What's the matter with Ubuntu (not the one with Unity but the modern one with Gnome)?
@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.
@surveyor I'm not sure what this point has to do with the thread.
I agree, more or less, but I don't know how it fits?
@ajroach42 that it's not always true that the past was better than now. To me it fitted, I'm sorry if it seem off topic. Thank you for the thread!
@surveyor My point was never that the past was better than now, just that we've grown more user hostile in recent years.
@surveyor Currently, nothing as far as I know.
They had an issue with sending keystrokes to amazon a while ago, but I think they are okay now?
@ajroach42 they're ok now. Probably it wasn't worth it. They now just collect some general info about hardware to give better support, make this info public and anonimized and also opt outable.
@surveyor I'd argue that nearly every method of anonymization is inadequate, but that's a c conversation for another day.
@ajroach42 so true , really good documents are like a key to the puzzle. I’m still trying to get that good at documenting that people don’t think it’s a puzzle anymore
@ajroach42 I wonder how much of #RTFM culture is a hangover from when the manuals were useful and most questions *were* clearly answered in the documentation
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.
@USBloveDog
That, and there's just this ingrained idea in FOSS communities that, if you need to understand what something does, or how it works, you should just read the code.
> 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)
@ajroach42 @USBloveDog
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.
RTFM is only hostile because documentation quality has gotten so poor.
@kurtm @ajroach42 what? No.
The lisp community has typically excellent docs and a legendarily RTFM attitude: it's not particularly helpful.
@ajroach42 RTFM culture is also extremely hostile toward people with disabilities that make reading manuals difficult.
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.
@suetanvil @ajroach42 No kidding.
You have to go back 30 years to get good computer manuals. I'd love to know what ROM addresses my WiFi card uses for what function. Good luck with that, it's embargoed behind an NDA.
Agree 100% on the 'gui is wady' fallacy. I'm not a technical user, and I still manage to find more and more tasks I prefer from the comfort of a decent terminal client.
@ajroach42
I'm a little unclear what you mean about user hostile?
They're user friendly for most of the things that non-tech people want to use them for.
But I'm not sure that I'm picking up what you're putting down.
@ajroach42
Ah nvm should have read all of your toots. Makes sense to me.
Brain-melting realization that this means that writing decent documentation, tutorials and FAQs is totally Cyberpunk behavior.
@RussSharek @ajroach42 And I'd argue that contributing to consistent, intuitive user interfaces would be equally cyberpunk.
No need to argue. :)
@klaatu carefully explaining on GWO how to install NetBSD is basically the most cyberpunk thing right now.
@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.
@paco I reject the premise that this is a good thing.
Computers are actively harming people in ways many don’t yet notice because of the user hostile behaviors I’m describing.
I am totally not a DIY person. Never used a dremel tool or a soldering iron. Or changed oil. But I managed to teach myself to do lots of small to medium repairs in my old car. It is surprising how easy it is to learn and how nicely card are engineered to let us build and repair them.
Cars have probably a very exhaustive and excellent design and requirement documentation. They have decent service manuals and very good parts catalogs. The are sadly reasons why those things are not widely available - but what if they were? There were still people who refuse to learn how to change the wheel (and this is documented today). But those who want to engage could do amazing things.
@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.
@rysiek This is an excellent point.
@ajroach42 thanks.
I think you should really put this whole thread in a form of a blogpost somewhere. It's important and valuable, and would be easier to link to and reference.
@rysiek I'm trying to get this one and the last one in to blog posts. We'll see how it goes.
@rysiek @ajroach42 I'm in a decent position to see this change happening.
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".
Depends on what you mean by RTFM culture. RTFM (said politely) if there's one that is good and simple to understand for new comers isn't a bad solution.
A bad solution would be too make a "it just works" software it's bad because if people don't have a minimum of knowledge in computing on long term it will gradually transform the free/libre software movement into a MS clone.
@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 The troll in me wants to say "git gud kid" but the real in me agrees.
@woah I'm not sure what you hoped to add to this conversation with this comment. I think I may have misunderstood, could you please explain?
@ajroach42 As an internet troll, I want to reply with "git gud" or "RTFM loser" but the sysadmin in me agrees that it's kinda shite that manuals for Linux are almost always too technical for a novince and scares lots of people away from learning.
@woah That initial response is so much a part of the problem, though.
It's this elitism that keeps people out of FOSS.
So, you know, maybe it's we sysadmins that need to 'get good'.
@ajroach42 Well yea, That's kinda what I was getting at.
@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...
@ajroach42 that's just bad business. I'm using CiviCRM, and they've intentionally left some options for form customisation off the options menu, so only can edit if I know PHP or JavaScript. Other parts are click of a button remove a field. We have money to support the project and do, but the principle of it seems greasy to me. We'd rather spend the money to feature improvement.
@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.
@acaiSG
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.
Look, this isn't an indictment against FOSS in general. I get that these projects are trying, I'm asking our community to help support these projects.
@ajroach42 gosh your whole thread is giving me a lot to think about. thank you.
@ajroach42 Yeah, https://xkcd.com/1343/ should've had another dot for "Tools that don't need a manual but have one anyways". Those really solve problems.
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.
@ajroach42 I'm not sure boycotting things like that really makes sense/is practical. For example: I would consider the manufacturer provided OS image on Lenovo Thinkpads unsafe.
@swiley So buy your thinkpad without an OS and install yourself?
And encourage others to do the same?
@ajroach42
I think at this point it's very important to define what you mean, and what you don't mean, by "user friendly".
@Wolf480pl Fair. I'll work on that.
@ajroach42 I really don't want us to fall into the trap of "it's simple: press a button, two pancakes come out, what's there to understand?"
@Wolf480pl I couldn't agree more.
I'm not equating "ease of use" with "user friendly." We don't need to hide technical complexity in the name of ease of use, as that is ultimately user hostile behavior.
@ajroach42 i refuse to buy android devices for which there is no root procedure
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.