5 ms·

I would argue that small command-line tools "the unix way" combined with a competently written -h help page is quite discoverable. Maybe not for a general compu

I would argue that small command-line tools "the unix way" combined with a competently written -h help page is quite discoverable. Maybe not for a general computer newbie, but certainly for people used to /other/ cli tools.

crispinb 9y ago
This only seems to work in practise for tools that are very small, otherwise exceptional writing is required (which, by definition, will rarely occur). I can't imagine (to pick a particularly extreme example) that anyone has ever learned to use git by reading the man pages. In contrast, even features in pretty poor GUI apps are by default generally discoverable.
- kemitche 9y ago
  I shudder to think how hard it would be - likely impossible - to use a bad git GUI if I didn't already know many of the git CLI commands. Even just, say, MS Word. If I don't know a feature exists, clicking around through dozens of menus isn't going to get me anywhere. For both CLI and GUI, Google or official docs are the only reasonable way to discover.
  - PhasmaFelis 9y ago
    > If I don't know a feature exists, clicking around through dozens of menus isn't going to get me anywhere. I find that clicking around through menus often teaches me about great features I didn't even know I wanted. Regardless of the cause, in practice, I find that it's much easier to get basic functionality out of a new-to-me GUI app than a CLI app. That may not be a fundamental properly of CLI, but it certainly is how all significant CLIs are written.
    - monkmartinez 9y ago
      So absolutely with you on this. Exploring visually is best for me as well.
      - abakker 9y ago
        Yep! I have nothing against CLIs, but imagine starting with the CLI in something like CAD. Sure, they have CLIs, but wow would that be hard. Without google, I'd have never learned any CLI stuff, and even as it is, I have no idea why the flags can't just be words instead of letters.
- thaumasiotes 9y ago
  The ssh man page is truly awful. I managed to read through it multiple times without finding the functionality I wanted, even devoting special attention to a section that turned out, later, to be purportedly "documenting" exactly that functionality.
  - TheKarateKid 9y ago
    This is why I usually only use man pages to reference a command-line option or as a quick reference. If you're new to a tool, a quick web search finds a much more informative tutorial which saves you time, despite being more verbose.
    - crispinb 9y ago
      Quite. And surely this is how pretty much everyone gets started with things like git? Conversely, novice use of even complex GUI apps rarely requires looking up a tutorial first, because you generally can just click or tap around and at least figure out minimally how to use it. Inexpert users (ie. nearly everyone) stop there. Obviously further reading is needed to make more extensive and/or efficient use of any tool. But at that point in my opinion we're beyond the reasonable boundaries of 'discoverability'
- wruza 9y ago
  For svn and specifically git GUIs with lots of options and insane defaults, I usually do not have a fcuking clue what exact command will yet another cool wrapper execute and how it will report back. Too many times I fought the result of people clicking around and completely messing the repo with no idea what they’ve exactly done. So, our company has a simple but strict rule: you’re allowed to update/pull/commit/push via gui, but nothing more and never touch any checkboxes in there. If you can’t spend time on one of your main tools docs to grasp what “merge -r 403:480 -c -473 ^/branches/rt0” does and how to command it, then sit there and code, folks will do maintenance for you.
  - crispinb 9y ago
    The parent was about discoverability -- you've argued that discoverability isn't necessarily useful for tools where people need to have some idea of what the tool is doing. There are many tasks where the user needs to have an accurate mental model and a grasp of the details. I completely agree with that. Still, GUI programs are very clearly more discoverable than cli ones. How far and where discoverability is the best approach to educating a user is a separate question.
    - wruza 9y ago
      >where people need to have some idea of what the tool is doing Not exactly. Wrappers can (and tend to) “enhance” and hide details from those who actually have idea. This kind of breaks discoverability into confusion, that’s what my rant was about.
- phaemon 9y ago
  >I can't imagine...that anyone has ever learned to use git by reading the man pages. Perhaps not, but they easily could. The Description section at the start of the man page says: "See gittutorial(7) to get started, then see giteveryday(7) for a useful minimum set of commands." And if you do `man gittutorial` it has, as you might expect, a tutorial on how to get started with git.
PhasmaFelis 9y ago
In theory, sure, but I've never seen a competently written -h page.

crispinb 9y ago

This only seems to work in practise for tools that are very small, otherwise exceptional writing is required (which, by definition, will rarely occur). I can't imagine (to pick a particularly extreme example) that anyone has ever learned to use git by reading the man pages. In contrast, even features in pretty poor GUI apps are by default generally discoverable.

kemitche 9y ago
I shudder to think how hard it would be - likely impossible - to use a bad git GUI if I didn't already know many of the git CLI commands. Even just, say, MS Word. If I don't know a feature exists, clicking around through dozens of menus isn't going to get me anywhere. For both CLI and GUI, Google or official docs are the only reasonable way to discover.
- PhasmaFelis 9y ago
  > If I don't know a feature exists, clicking around through dozens of menus isn't going to get me anywhere. I find that clicking around through menus often teaches me about great features I didn't even know I wanted. Regardless of the cause, in practice, I find that it's much easier to get basic functionality out of a new-to-me GUI app than a CLI app. That may not be a fundamental properly of CLI, but it certainly is how all significant CLIs are written.
  - monkmartinez 9y ago
    So absolutely with you on this. Exploring visually is best for me as well.
    - abakker 9y ago
      Yep! I have nothing against CLIs, but imagine starting with the CLI in something like CAD. Sure, they have CLIs, but wow would that be hard. Without google, I'd have never learned any CLI stuff, and even as it is, I have no idea why the flags can't just be words instead of letters.
thaumasiotes 9y ago
The ssh man page is truly awful. I managed to read through it multiple times without finding the functionality I wanted, even devoting special attention to a section that turned out, later, to be purportedly "documenting" exactly that functionality.
- TheKarateKid 9y ago
  This is why I usually only use man pages to reference a command-line option or as a quick reference. If you're new to a tool, a quick web search finds a much more informative tutorial which saves you time, despite being more verbose.
  - crispinb 9y ago
    Quite. And surely this is how pretty much everyone gets started with things like git? Conversely, novice use of even complex GUI apps rarely requires looking up a tutorial first, because you generally can just click or tap around and at least figure out minimally how to use it. Inexpert users (ie. nearly everyone) stop there. Obviously further reading is needed to make more extensive and/or efficient use of any tool. But at that point in my opinion we're beyond the reasonable boundaries of 'discoverability'
wruza 9y ago
For svn and specifically git GUIs with lots of options and insane defaults, I usually do not have a fcuking clue what exact command will yet another cool wrapper execute and how it will report back. Too many times I fought the result of people clicking around and completely messing the repo with no idea what they’ve exactly done. So, our company has a simple but strict rule: you’re allowed to update/pull/commit/push via gui, but nothing more and never touch any checkboxes in there. If you can’t spend time on one of your main tools docs to grasp what “merge -r 403:480 -c -473 ^/branches/rt0” does and how to command it, then sit there and code, folks will do maintenance for you.
- crispinb 9y ago
  The parent was about discoverability -- you've argued that discoverability isn't necessarily useful for tools where people need to have some idea of what the tool is doing. There are many tasks where the user needs to have an accurate mental model and a grasp of the details. I completely agree with that. Still, GUI programs are very clearly more discoverable than cli ones. How far and where discoverability is the best approach to educating a user is a separate question.
  - wruza 9y ago
    >where people need to have some idea of what the tool is doing Not exactly. Wrappers can (and tend to) “enhance” and hide details from those who actually have idea. This kind of breaks discoverability into confusion, that’s what my rant was about.
phaemon 9y ago
>I can't imagine...that anyone has ever learned to use git by reading the man pages. Perhaps not, but they easily could. The Description section at the start of the man page says: "See gittutorial(7) to get started, then see giteveryday(7) for a useful minimum set of commands." And if you do `man gittutorial` it has, as you might expect, a tutorial on how to get started with git.

PhasmaFelis 9y ago

In theory, sure, but I've never seen a competently written -h page.