I don't think that's true. Three ways that are de-facto standarized for CLIs for discoverability (where UI has almost no de-facto standards like this):
- `man $program` - Usually shows EVERYTHING you can do with the tool
- `$program --help` - shows a brief help with flags, parameters and commands
- `$program $cmd --help` specific help for that command
Most CLI tools implement these and most of everyone who is using a terminal daily knows about those three ways.
In the GUI world, you sometimes have a "Help" link in the menu bar, that either opens a little widget or a web page. Nothing like man pages for GUIs.
It's frustrating, but people often seem to say "discoverable" when they mean "doesn't need a manual" or "intuitive". So CLIs that don't conform to standard patterns, or whose subcommands/options don't make intuitive sense would be "non-discoverable".
But also, well-written manuals and usage/help screens are becoming increasingly rare these days. Technical writing is time consuming and people choose not to do it.
Good points, especially about the lack of documentation. Regardless of the type of interface, people need references to go with them.
Discoverability can mean more than discovering features of the app too. To me, I think more about discovering information contained within it, seeing things I wouldn't have noticed in a command line experience. In a complex system like server automation, there's actually a lot of potential value in GUIs making it easier to see correlations between things or notice problems or discrepancies before they become bigger issues.
I've been a command line-first user since the 90's, but I would hesitate to recommend this over other solutions specifically because of the lack of GUI.
Apple did something like this with A/UX back in the day (their variant of Unix which apple sold for its 68k machines). https://en.wikipedia.org/wiki/A/UX The tool that did this was called Commando; I'm not sure if it was hand-crafted, or automatic.
A huge part of the problem is that `man` pages really are only softly standardized, and just, commandline options in general are just softly standardized. They don't all obey the same rules for spaces, capitalization, usage of dashes, etc - they're close, but it's far from consistent.
What we ought to have done at some point, would have been to rebuild the whole suite of commandline utils - to make them all do an ironclad standard, and probably even make them all spit out a totally normalized data format like JSON, man pages included, so that external tools could be built around them way easier without everyone having to write their own parser (or - having to write a generalized parser with tons of 'special-case exemptions' for all the CLI tools that break the rules).
There have been several attempts, but nobody's been willing to do the big "rip off the bandaid" and take the pain of breaking legacy scripts.
We have had automated GUIs generated for command line utilities since PowerShell 2:
PS C:\> show-command get-childitem
will popup a GUI form for all the options get-childitem takes. It's basically useless because it's a dump of all available parameters. At least they're in alphabetical order, but there's no hint which ones you might want or not want.
Not sure it'd be trivial unless the documentation is really good. I have, however, seen TCL used to good effect of GUIfying a CLI, and providing a scriptable interface so that you can access features that don't translate well to the GUI or (for whatever reason) haven't been made directly accessible in the GUI.
I'd say its less common for a project to have budget for a technical writer. I think there are plenty of people who have stellar writing ability, it's just nobody is willing to pay for it.
I remember back when I ran Ironport appliances it came with a giant manual - maybe 1000 pages. It was very well written, had CLI excerpts, explained theory, etc. It was amazing.
Companies see things like admins, technical writers, configuration management as excess. Technology today has reduced the need for these specialist-but-not-core-to-the-business roles. So the work is increasingly piled on the specialist in other fields rather than being a specialist position of its own.
"I'm not paid to write manuals" is a common refrain in places I've been. The developer wants to write the code, maybe write the spec and design document. But they have no interest in writing the manual because "it's not my job." Only, today, it is their job because their employers (contrary to last century) don't employ writers on staff and contracting for fast changing documentation to keep up with fast changing systems isn't worth the effort. So it's up to the dev.
Same with many other tasks. There have been some really good articles about the impact on professions like professors, teachers, doctors and others as their workload has increased. Why? Because technology has reduced each individual task to something small, but cumulatively it's drowning them (and us). Something has to give. The shifted work makes sense until you look at the aggregate impact.
In the case of doctors, they have little they can avoid doing so they just drown in work. Teachers are made to work 12-16 hour days during the school year. But we, the programmers, get to skimp on these things (and hurt our users) because it hasn't yet hurt our bottom-line or cost any lives (safety critical systems still do a better job here out of necessity).
Don't forget `-h` "chastise me for not using --help, and don't show the help".
and `-h` print "usage: $program [TBhrRtzFwbvjEBUQ]"
This is assuming all the commands are in one binary, and you know what the binary is (compare 'yum install' and 'yum search' with 'apt-get install' vs 'apt-cache search').
> Most CLI tools implement these
Most? You can see there's a big competing pattern of having multiple binaries with the same prefix like ssh ssh-agent ssh-keygen, dbus-FOO dpkg-FOO apt-FOO snmpFOO ldapFOO.
And there are plenty which don't have this "clearly delineated sub-command" like git has.
> where [GUI] has almost no de-facto standards like this
The massive main de-facto standard a GUI has is showing you important things up front and hiding irrelevant and uncommon things away. With a CLI you see nothing until you --help then you see everything. There's no indication of what's a common path through the tool.
It's not showing options in alphabetical order. Am I to infer that "-sigopt nm:v" is more common, more used, more important, than "use SHA1" because it's higher up in the list? If not, why is it higher up in the list?
Hamburger menu? Right-click on a thing to show you a context menu of things you can do with a thing? A central content area with "tabbed sections" along the top (real tabs or links like a menu bar)? Mouse hover-and-pause tooltip? "select an item and press F1 for help"? Have a username link or avatar picture behind which your user-specific options are? Are these not large and common "de-facto standards" in GUIs?
> You can see there's a big competing pattern of having multiple binaries with the same prefix
One could create an entire ecology of tools that operates as a sort of compromise: Have a family of separate programs named with a common prefix (e.g., foo-), and a dispatch program (foo) that, when run like
foo bar options
dispatches to foo-bar with the options, and when run like
foo [-h|--help]
prints a help message and then lists every foo- program on the PATH, incorporating the whatis output where available. (That last bit requires man pages to work, but you can't very well tell people to read a manual that doesn't exist.)
I have used this strategy at work with considerable success.
I'm a big CLI user, but my primary gripe with these sorts of interfaces vs a GUI is when they have a huge number of nested sub commands. I often find myself searching through the tree of possibilities running --help on every single level just to do something simple. Especially if what I'm trying to do may exist in disparate sub commands. With a web interface there'd likely be some kind of nested menu or dropdowns that offer more of a sense of the overall arrangement at a glance.
I'm always happy to have access to the CLI to be able to script things, but if it's the only interface to a service with many features it can be awfully cumbersome.
Sometimes with these deeply nested do-it-all CLIs I feel like I'm playing a text adventure trying to navigate a maze, constantly typing /look and /examine. Often these tools have so many sub commands that a man page is not helpful if it exists at all.
The best CLIs are interactive. Try a Cisco console. At any point they have a limited search space and you can just type "?" to get autocompletion for what you're doing. Everything is hierarchical and very discoverable. You can negate things with "no" to unset properties and such.
Even zsh with various plugins or fish feel rather primitive in comparison.
I typically write bash wrappers in situations like that. You could also write in a real programming language that shells out to the CLI tool if it gets too complicated.. even better if there's a library that does away with the need of shelling out.
Hah, `man aws` prints `No manual entry for aws`. You can of course dig around the help pages for each individual subcommand, but it doesn't give a very good idea about how the resources stitch together. More importantly, you miss out on the wizard-like behavior for spinning up new resources without needing to provide a reference to each upstream resource (the GUI can create these upstream resources for you or let you bring your own depending on how you navigate the creation wizard). I'm sure this is all possible with a sufficiently well-designed CLI (`eksctl` does this for EKS), but no such CLI exists for AWS holistically and these are pretty rare for any kind of application.
Also, personally I really dislike man pages--paging through tons and tons of text that has nothing to do with my use case to find the one or two bits that are actually relevant is not really my idea of a good time. They are the most flat-footed solution to the discoverability problem, but they leave a lot to be desired.
To be clear, my comment was about using `/<search term>`, not manually paging. It's still a very unpleasant experience. If you're interested in a particular concept, but you're not sure what your program calls it, good luck. Even if you're looking for a particular flag (e.g., `-c`) you can have hundreds of search results to parse through depending on the size of the man page. I personally don't enjoy this experience.
- `man $program` - Usually shows EVERYTHING you can do with the tool
- `$program --help` - shows a brief help with flags, parameters and commands
- `$program $cmd --help` specific help for that command
Most CLI tools implement these and most of everyone who is using a terminal daily knows about those three ways.
In the GUI world, you sometimes have a "Help" link in the menu bar, that either opens a little widget or a web page. Nothing like man pages for GUIs.