The problem is mainly one of discoverability. The non-programmer in the examples says "simple" when they mean "discoverable". The programmer says "simple" when they mean "not much code complexity".
Of course you disagree.
All the examples - installing and using a package manager, running a command line program - are "simple" from a software point of view, but they're not at all "discoverable". To understand the steps you need to memorise a seemingly meaningless sequence of text.
Of course, the programmer has a very strong underlying model of all of this, and so these commands seem straightforward. But even for a programmer, this stuff isn't very discoverable. I'm frequently stumped by man pages, and end up having to hunt down an example of how to use a particular command line application on Stack Overflow. I've been using linux for decades and I still often can't find where an applications binaries or config live, and I still very often have to type some magic incantation I found on Stack Overflow into the command line, because my mental model of some subsystem of Ubuntu isn't complete enough to know it. None of these things are discoverable - I've got more patience than most in searching Google and Stack Overflow, but it's not exactly a desirable way of using a computer. I would prefer it if there was a nice button in the system settings that did what I wanted.
When things aren't discoverable, they become hard. And people don't generally like doing hard things. That's not exactly a revelation.
man, that's a good talk. I've got some decompilecting to do in a few places.
I loled at the beginning, when he talks about (in 2011) how "all I see on hacker News is people talking about how great and awesome all this new stuff is and nobody ever questions it, asks if this stuff is adding more problems". The culture must have shifted in the interim.
Windows does that, and its regular users barely visit Control Panel, not to mention .msc-s and other system menus, e.g. Security or Sharing tab. When something breaks or they have an idea that isn’t in a nearby menu, they call a nearby programmer for help. Your sentiment is agreeable, but we are still unable make interfaces you want.
There probably even is a button or a sequence of ui actions in your system for half of things you wanted. But these are less discoverable than a bash pipe available right there on SO, three clicks away rather than ten+ that will change location and names with the next update. It becomes hard either way, but only a stable and replayable way wins.
> When something breaks or they have an idea that isn’t in a nearby menu, they call a nearby programmer for help.
No they don't. Normal people don't have programmers on call. They google the error message and do whatever the classiest-looking page they find tells them to do, which usually starts with opening the Control Panel. Honestly, the same thing that programmers do when they hit something they don't understand, except programmers are better evaluators of classiness irt help pages (due to the mental model.).
For a loose definition of "programmers", sure they do. Maybe it's a sysadmin, maybe it's a teen who writes/ builds game mods, but IME most normal folks have someone at work or someone in their family they can ask/ harass, and they'll do this before they'll start typing error messages into a web search.
Folks will come and ask for help but then you have to tease out of them what the problem was. The entire idea of "I got this error; I will look up this error" is _foreign_ to most normal folks. It is grand when they came with an error message in hand.
But even when someone has an error message, they often turn their brain off: I worked with a developer who would send screenshots of a text error rather than just copy and paste it, which would force one of us to retype what he wrote into a web search.
> I worked with a developer who would send screenshots of a text error rather than just copy and paste it..
I've worked with one like that. I got fed up so I just took to walking back to my desk and telling them to google it to see what the general consensus is, when they can tell me more about it I'll come back. Did that enough times till they got 'used' to not being lazy and at least tried to understand the issue before yelling for help.
Was harsh at the time but they knew they were being lazy and as devs we are paid to find solutions. I think that's the critical thing in this, we're not only incentivised into naturally and habitually finding solutions to things, but also we are failing when we don't. We're failing for our expectation of our own analytical capability. Also we work with devs, or dev-like people so we get used to talking to people who will either keep up with us when we're rattling down a rabbit hole of thinking, but sometimes will gleefully join us in it to try to find the solutions.
I think that's the crucial thing here. We're applying our expectations of ourselves/peers into personality traits that find solution finding completely alien, who not only don't think 'this is for me to understand', don't even approach the thought that they can potentially do something to fix it, even at a very small level.
The things we do everyday as easily as breathing, to a lot of people is magic, and that's really not a good thing (“Any sufficiently advanced technology is indistinguishable from magic.”).
I think the root problem is that writing documentation sucks and people just do the bare minimum. I am hoping that AI making docs easier to create will help make them more usable all around.
man pages started out as a problem. If you don't already know a lot of foundational stuff, it's very difficult to bootstrap yourself with it. There are so many things that say something like "see man fizzlewizzle (3)" or something. I've been a developer for nearly 40 years (mostly in Windows, barely dabbling in linux) and I've yet to figure out what the heck that number means, or how I might predict what the correct number is when I want to look something up myself.
> I've been a developer for nearly 40 years (mostly in Windows, barely dabbling in linux) and I've yet to figure out what the heck that number means, or how I might predict what the correct number is when I want to look something up myself.
You usually don't have to care unless you're writing them because it only matters to a user when there are man pages of the same name in multiple sections.
> I'm frequently stumped by man pages, and end up having to hunt down an example of how to use a particular command line application on Stack Overflow.
If you're not aware of tldr [0], I highly recommend it.
man(1) pages on linux are almost all terrible. Unworthy of inclusion in any manual. Proper manuals have examples of use. Many linux man pages don't even discuss (or list, even!) return codes or failure modes.
Some of the manpages for utillinux (e.g., chsh, useradd) are pretty barebones and don't include examples, but off the top of my head I can't think of a major GNU utility that doesn't have EXAMPLES sections in its manpages. GNU coreutils, find, sed, and grep all have such a section in their manuals.
GNU ls's manpage has no examples, but it's also a thousand words long so it hardly seems fair to characterize it as bare-bones.
All in all, I find that manpages on Linux are usually pretty good, particularly compared to systems like MacOS where many daemons and utilities seem to have no manpage at all. People are far too quick to slag manpages, which probably has something to do with the `man` utility itself being a bit archaic. Common Linux desktops could probably do a better job of advertising GUI-based manpage readers like khelpcenter.
I'd like slightly fancier system (no, not info), but being able to look things up without leaving the terminal is so underrated imo. It makes looking things up a lot faster.
For me, 99% of the time I use -ltrh and -ltrha. But instead of -R, I use other utilities like fzf, find, or tree. Tree is really nice for a quick overview of directory structures.
Yeah, I really don't understand the aversion to examples. The sorta-standard format for man pages is... extremely confusing, even after a decade of using them.
You do realize that writing good docs takes time, skill, and effort, right? Not to mention the docs you're blanketly scorning at were most likely written on someone's spare time who has no obligation to do so.
When you have some people not doing it, that's fine, they own their time. When you have have almost no one doing it, that's a cultural issue. I'm saying Linux/Unix man pages have inherent and probably very old cultural issues leading to a lack of baked-in examples.
Stallman's sad devotion to that ancient religion... ITS has been effectively dead for how many decades now, but by god we're gonna force everybody to use a port of their online documentation system if we can!
At least we're past the bad old days when you'd open a man page and it would just be a stub saying "look at the info docs, IDIOT"
This is what microsoft did well with powershell's help system. They have examples. Tons of them.
Why man pages do not is beyond me when most of the time, an example or two is all we need. I bet most people go to the man pages and then google for examples because the man pages weren't helpful.
ss64.com is good to me as well. There's like 4 ways to write filters in powershell and I am never sure which syntax I need for a given command or if I'm supposed to use |?{ instead.
> All the examples - installing and using a package manager, running a command line program - are "simple" from a software point of view, but they're not at all "discoverable". To understand the steps you need to memorise a seemingly meaningless sequence of text.
In a big enough organization, document sharing setup and program installation for non-technical users should be performed by sysadmins. There's a good chance if someone needs something, everyone will need it, so with proper device management tools they can make it discoverable/preconfigured for everyone.
The new CLI sub-command model helps here I think. Many commands by default now list out their sub-commands when not given one and each sub-command has it's own help output. This plus command line completion really does a good job at discoverablility IMO.
Oh and "memorise a seemingly meaningless sequence of text" makes no sense as all sequences of text are meaningless until we assign them meaning which is what you're doing learning a CLI.
I've taken to having the default behavior of a CLI program be to display the URL of the documentation. This seems obvious to me, but it was a long time before I thought of it, and I haven't seen it elsewhere.
I didn't see a need to add a GUI as a web browser will do nicely.
I've always used Android phones, but my company recently stopped supporting them and told me they have to issue me a new phone - this time an iPhone.
And I'm utterly lost. At one time, Apple was said to be the high priests of user experience, with intuitive interactions that would just work the way you expect. This seems to have fallen by the wayside, pushed out by making it more sophisticated I suppose. Because things that I do instinctively on Android, I just can't figure out how to do. I've had the phone a week now, and I still haven't figured out how to do a "Switch App" (like Alt-Tab). A few times I've accidentally hit it, but I can't figure out what the trick is.
I don't mean to say that it's objectively bad, but it sure has erected a wall against anyone who might migrate from Android.
Yeah, I had to use an iPhone for a while, and found it incredibly frustrating to figure out how to do pretty much anything. Everything I wanted to do involved a whole bunch of blind searching.
I don't think it's the iPhone's fault. I think it's because I am used to Android.
Both Android and iPhone are very unintuitive and lack discoverability. You learn how to use them with experience.
> Apple was said to be the high priests of user experience
People say that, I always wonder how much of that was true. It took me three days to figure out how to get my iPad Touch to stop repeating a single song. I don't know how a single song got selected on repeat.
Affairs will begin to favor the "programmer" definition of simple with the advancement of conversational models. A chat bot that responds to your prompt with command line flags is going to appear simpler than an answer about advanced physics or math.
Of course you disagree.
All the examples - installing and using a package manager, running a command line program - are "simple" from a software point of view, but they're not at all "discoverable". To understand the steps you need to memorise a seemingly meaningless sequence of text.
Of course, the programmer has a very strong underlying model of all of this, and so these commands seem straightforward. But even for a programmer, this stuff isn't very discoverable. I'm frequently stumped by man pages, and end up having to hunt down an example of how to use a particular command line application on Stack Overflow. I've been using linux for decades and I still often can't find where an applications binaries or config live, and I still very often have to type some magic incantation I found on Stack Overflow into the command line, because my mental model of some subsystem of Ubuntu isn't complete enough to know it. None of these things are discoverable - I've got more patience than most in searching Google and Stack Overflow, but it's not exactly a desirable way of using a computer. I would prefer it if there was a nice button in the system settings that did what I wanted.
When things aren't discoverable, they become hard. And people don't generally like doing hard things. That's not exactly a revelation.