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.

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

@USBloveDog

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.

@ajroach42

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

@ajroach42

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.

@ajroach42

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.

@ajroach42

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.

@suetanvil @ajroach42

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.

@suetanvil @ajroach42 The pace of development may be too frenetic on the whole. An #antifragile system likes small volatility but too much chaos at a local level will disrupt the global state.

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

@ajroach42

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.

@bhtooefr @ajroach42

No need to argue. :)

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

@saper @paco Lots of the same points could be made re: computers.

@saper @paco And for those that don't want to, they don't have to.

But those who want to should be able to.

@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".

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

@ajroach42

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.

@sheogorath

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 My favorite thing is how Amazon stopped updating my third gen Kindle Fire except to patch holes people find to install a custom and up to date Android.

@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 This is something I like about Serum. It's made by some math whiz supernerd musician, but it's extremely straightforward and well-documented,

@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 may disagree about refusing to buy tech ... and say that we're not their yet in terms of viable options. Open hardware is gaining momentum though!

@uranther Buy the least problematic software and hardware.

If you're going to buy something with a problematic progeny, help promote the tools to make it safe, yeah?

@ajroach42 i refuse to buy android devices for which there is no root procedure

@ajroach42 the engineering part of computer engineering just died off...

@ajroach42 I suppose now everything is trying to screw the user because the user is no more the customer

@ajroach42 reading maps is fun and you can't tell me otherwise

@ajroach42 a conversation that happened when i was in college:
"wait are you looking at google maps?"
"yeah"
"for where?"
"uh..." *debating lying* "finland"
"why the fuck are you looking at a map of finland"
"idk this happens sometimes"

@xyzzy @ajroach42 did he have permission from proper finnish authorities?

@xyzzy @ajroach42 and you can't tell me orienteering doesn't just sound fun either - it's dripping with potential adventure

@djsundog @ajroach42 weirdly for someone who likes maps i have no internal compass or sense of direction whatsoever

my mental map of places kinda looks like one of those scribble drawings kids used to do in ms paint

@ajroach42 @djsundog with some question marks drawn next to it

@djsundog @ajroach42 so um yeah if i tried orienteering i might never be seen again

@xyzzy @ajroach42 but that's the trick - you don't need a mental compass if you have an actual compass and a good map ;)

@ajroach42 That's a great way for him to respond, though. It would have been so much worse if he'd shut you down or ignored it.

@gbrnt It was great! He was the department head, and he started shipping this stuff out to all the classes in CS. They started emulating that style of explanation, and that language in their own slides.

As long as the students didn't notice that the material was written at 8 year old from the 80s, it worked very well.

@ajroach42 oh cool!

@ajroach42 that's awesome!

@ajroach42 This is really an interesting thought. I started around the same age, and the PC existed weeks before christmas, so I wasn't allowed to used it and I swear, I read literally every manual 2-3 times before I started it first. And it really helped.

On the other hand - when I try to learn new stuff, I try to start with total newbie tutorials, books for children, and other stuff. The more stupid the author thinks you are, the more useful what he writes usually is. :)

@ajroach42 as a programmer: there is never any budget for documentation. If you get forced to do some you usually cobble some screenshots together. But then nobody ever really complains so i guess nobody expects anything.

@wittler @ajroach42 "the software is done. It's just missing it's documentation"
It's a lie.

Doc is part of the software.

It's our responsibility to tell this to our managers.
Without doc the software is unusable / unmaintainable / garbage / very expensive / whatever.

They're there for doing the business part of software engineering - not for poisoning the product with misknowledge.
(I know that the last sentence is a bit utopian)

@upshotknothole @ajroach42
It should be, but programs I do are usually done on a Budget, the customer doesn't want to pay much Money on it so the Budget is as small as can be done. And since nobody really gives me as a developer time to write a documentation it is usually not done.

On the other Hand since no documentation is done nobody is asking for any anyways :)

@wittler @ajroach42 the manager represents the business side of software. You (the dev) represents the technical side of software.

You need to meet in the middle. Software without the manager is un-sellable for various reasons (for example, tech-purism). Software without the sev is un-sellable for various reasons (no in-depth support can be offered, ... etc)

@wittler I've worked in development and support for the last 10 years.

If you've never heard anyone complain, it's because your dev team is isolated from your users by a strong support team, or because no one is listening.

Our users *beg* for documentation, and it takes an act of god (or, in this case, the CTO) to get anyone involved (from the product owners to the QA team to the developers to the technical writers) to actually take the time to write it.

@ajroach42
Sort of.
I do custom programming for Business. (yes, SAP...).
Usually I get into contact with the users but usually it isn't a very big number of users.
I work as a programmer for 20 years now at various companys.

@wittler When I take on freelance custom development, I won't take on a project if the financier isn't willing to pay for me to write documentation, because I recognize that poorly documented software results in either more support work or less client satisfaction.

I won't ship software without documentation, and I encourage everyone else I know to do the same.

I recognize that this isn't always possible, but the times I have broken this rule have more than demonstrated it's necessity to me.

@ajroach42 the idea is that software should be "easy enough not to need a manual"

it's not elitist in the sense I normally think of... it's more perhaps naïve thinking that they can make UIs that state everything through implication

the "elite" technical world rejects this notion of the consumer world, and quality documentation is valued by programmers and admins to get started with and reference (but sites like google and SO are hurting that ideal)

@ajroach42 I remember choosing SuSE Linux back then their 6.x series was current precisely because it came with a 400+ page printed manual that covered installation, administration, and introduced major software packages. Likewise, I chose to switch to OpenBSD because they take documentation seriously.

@starbreaker I started using linux because I got a copy of Mastering Red Hat 7.1 from a discount book store.

It was 1000 pages, and eye opening.

@ajroach42 I suspect that this behavior by orgs can be explained by the depth of the markets that they're working in and the degree of opportunity (return) that they perceive there is to be had from investing in such measures. If competitors are in ready supply and consumers are seemingly willing to put up with low information about using products, they may think that it's likely that providing more info will barely decrease the probability of consumers going with competition.

@ajroach42 I'm thinking about this in terms of that by not providing info on how to use X, orgs that produce X are shifting costs of using X and its possible substitutes (competitors products, if they lack significant differences) upon the consumer rather than bearing them themselves.

This is similar to #gameTheory scenarios, where if you invest in info about X but your competitor doesn't, they get to be more profitable and you financed the ease of use of their product, too.

@bthall that’s a potential explanation for how we ended up in this situation, it doesn’t justify the situation or negate the fact that it’s a user hostile situation.

@ajroach42 my Dad just got an #iPhone, his first #Apple product of any kind, and he's livid that there's no manual included. 😅 He thinks this has the effect of discriminating against older consumers that don't know how to use such #tech.

@craigmaloney

I agree. Add in wikis and support forums, too.

In addition to knowing where to look, they also require understanding the language used within. Especially with man pages, they can be very oblique and difficult to understand. (This is not a rule, and there are plenty of examples of excellent man pages, but enough of them are dense and difficult that it can turn people away from Man Pages as a general rule.)