7 ms·

The problem is mainly one of discoverability. The non-programmer in the examples says "simple" when they mean "discoverable". The programmer says "simple" when

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.

threatofrain 4y ago
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.
- remram 4y ago
  Something can be easy while not being simple.
  - deleted 4y ago
    [deleted]
wruza 4y ago
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.
- pessimizer 4y ago
  > 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.).
  - brightlancer 4y ago
    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.
    - biggedyb 4y ago
cassianoleal 4y ago
> 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. [0] https://tldr.sh/ https://tldr.sh/
- jabroni_salad 4y ago
  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.
  - zikduruqe 4y ago
    I also use http://cht.sh http://cht.sh from time to time.
- tuatoru 4y ago
  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.
  - packetlost 4y ago
    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.
    - spacemadness 4y ago
      “you should be smart enough to figure this out from here” bravado probably for some cases.
      - soraminazuki 4y ago
        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.
remram 4y ago
Reminds me of Rich Hickey's classic talk "Simple made Easy": https://paulrcook.com/blog/simple-made-easy https://paulrcook.com/blog/simple-made-easy Simple and easy are not the same thing.
- pksebben 4y ago
  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.
908B64B197 4y ago
> 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.
flerchin 4y ago
I feel like there's a fundamental understanding of man-pages that we are just missing. I find myself in the same boat quite often.
- CWuestefeld 4y ago
  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.
  - andrewf 4y ago
    "man man" explains the section numbers.
    - throwing_away 4y ago
      Maybe we need a fork of `man` that reads the page in a sexy tts voice while showing minecraft footage on half the screen.
      - biggedyb 4y ago
        Or AI generated animated walkthrough content straight into PluralSight... ...and I write this partly in jest as I absolutely would use that.
      - justherefornews 4y ago
        Cause this is what the kids want these days amirite?
  - wolrah 4y ago
    > 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. https://en.wikipedia.org/wiki/Man_page#Manual_sections https://en.wikipedia.org/wiki/Man_page#Manual_sections 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.
spencerchubb 4y ago
I wish CLIs had better discoverability. That's one of the first principles of UX. There should be a library that makes it easy for developers to include a basic GUI with a CLI
- WalterBright 4y ago
  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.
- JohnFen 4y ago
  > That's one of the first principles of UX. And yet, in the world of GUIs, discoverability is getting increasingly rare. I don't think it's prioritized at all anymore.
  - CWuestefeld 4y ago
    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.
    - disgruntledphd2 4y ago
      Double tap the home button and it brings up the app selection screen. Took me an embarrassingly long time to figure that out some years back.
eikenberry 4y ago
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.

threatofrain 4y ago

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.

remram 4y ago
Something can be easy while not being simple.
- deleted 4y ago
  [deleted]

wruza 4y ago

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.

pessimizer 4y ago
> 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.).
- brightlancer 4y ago
  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.
  - biggedyb 4y ago

cassianoleal 4y ago

> 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. [0] https://tldr.sh/ https://tldr.sh/

jabroni_salad 4y ago
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.
- zikduruqe 4y ago
  I also use http://cht.sh http://cht.sh from time to time.
tuatoru 4y ago
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.
- packetlost 4y ago
  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.
  - spacemadness 4y ago
    “you should be smart enough to figure this out from here” bravado probably for some cases.
    - soraminazuki 4y ago
      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.

remram 4y ago

Reminds me of Rich Hickey's classic talk "Simple made Easy": https://paulrcook.com/blog/simple-made-easy https://paulrcook.com/blog/simple-made-easy Simple and easy are not the same thing.

pksebben 4y ago
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.

908B64B197 4y ago

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

flerchin 4y ago

I feel like there's a fundamental understanding of man-pages that we are just missing. I find myself in the same boat quite often.

CWuestefeld 4y ago
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.
- andrewf 4y ago
  "man man" explains the section numbers.
  - throwing_away 4y ago
    Maybe we need a fork of `man` that reads the page in a sexy tts voice while showing minecraft footage on half the screen.
    - biggedyb 4y ago
      Or AI generated animated walkthrough content straight into PluralSight... ...and I write this partly in jest as I absolutely would use that.
    - justherefornews 4y ago
      Cause this is what the kids want these days amirite?
- wolrah 4y ago
  > 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. https://en.wikipedia.org/wiki/Man_page#Manual_sections https://en.wikipedia.org/wiki/Man_page#Manual_sections 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.

spencerchubb 4y ago

I wish CLIs had better discoverability. That's one of the first principles of UX. There should be a library that makes it easy for developers to include a basic GUI with a CLI

WalterBright 4y ago
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.
JohnFen 4y ago
> That's one of the first principles of UX. And yet, in the world of GUIs, discoverability is getting increasingly rare. I don't think it's prioritized at all anymore.
- CWuestefeld 4y ago
  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.
  - disgruntledphd2 4y ago
    Double tap the home button and it brings up the app selection screen. Took me an embarrassingly long time to figure that out some years back.

eikenberry 4y ago

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.