Back to discoverability, is there a way to make CLI "more discoverable"? Reading the man page doesn't count. Like can we combine the advantages of CLI with the discoverability of GUIs? I wanna have the cake and eat the whole thing.
I've always found --help (or help <command> for tools breakin the "standard") and man pages massively more discoverable than any gui.
There are two well known entry points "--help" and "man". There has been much convention standardization with operating system guis, still they have many, many possible entry points. not all programs use same ones, use in same way. And webapps/pages are complete non-convention chaos.
both --help (but not "help <command>" (a reason they are "wrong") and man are 1 level deep and show you the entire ui, all at once. That is definition of discoverable! One action, i've discovered everything.
GUIs are deeply nested. And context sensitive so it may not even be possible to see actions until certain condition is met. The definition of opaque and undiscoverable.
This is a feature, not a bug.
For me, browsing 20 pages of --help or man is a discoverability nightmare. I don't want to wade through arcane option after arcane argument.
The GUI gives me a well-organized top-level understanding of the program: organized menus, and organized panes (panels/palettes/tabs/etc.). Then I can drill deeper into dialog boxes and tool settings as needed.
It's far more efficient to quickly browse a GUI to figure out the lay of the land, than it is to wade through what is essentially the reference manual of a CLI tool.
Reference manuals are the opposite of discoverability.
Badly made GUIs are. I started my career developing desktop software. Both Apple and Microsoft used to publish guides for building proper GUIs for their platforms. Our UX designers and PMs were enforcing those vigorously.
On Windows, every feature had to be represented in the menu of the main window. See, right there, by going (not even clicking on) every menu item you will learn about existence of every feature. Photoshop is still like that.
Most frequently used actions deserved two additional things: a hot key and a toolbar button. Each toolbar button had to have a tooltip. See? Right there, by going over the toolbar one could quickly learned the most important features.
Using windows, splitters, panes, tree views and tabs - there was logic behind those choices, and having standardized set of UI controls allowed users to learn software much more rapidly.
Modern web "applications" are crude by comparison. There's no standardized way to discover anything. Is it a button? Is it a dropdown? Is it just a strange background to display an error? Things auto-hide and auto-appear for no reason, you have to move mouse around (or practice every swipe variation you're familiar on mobile). Hotkeys are an afterthought, even resizing the browser or even scrolling sometimes breaks things.
I am not going to name names, but we tried to use one of web-based conferencing apps a few years ago. The UI it offered for joining a call (the URL you'd include into a meeting invite) was so bad that nearly 30% of people could not find out how to join. That's basically the only thing that page needed to provide, yet their UX people managed to obfuscate it so much that users sat waiting & thinking that something is about to happen instead of clicking the "join" button... Ughh.
There's so much demand for software right now, every industry needs more... There is severe shortage of talent for everything, from engineers to UX designers and product managers. Eventually there will be an equilibrium and we'll have professionals design and program GUIs again.
I am a CLI-first person, but there's no doubt in my mind that a well-done GUI massively flattens the learning curve for a new app.
See this article (full disclosure: written by me) that talks a bit more about some of the tradeoffs between CLIs and GUIs from a UX perspective: https://medium.com/design-ibm/real-developers-dont-use-uis-d...
There's also this interesting project that attempts to bring some of the discoverability and other benefits of graphical UIs to CLIs: https://github.com/IBM/kui . Would love to see more work in this area.
Have you seen git's help/man? That's at minimum 2 levels deep.
macOS does have a standard Help menu, and you can even live search from within it; it'll find a command within the menus and show you where it is, even if it's deeply nested. Or it will search through help topics if the application provides them.
> And context sensitive so it may not even be possible to see actions until certain condition is met.
That's gotten worse as developers have jammed more and more features into applications, to where they can't lay out their commands in the traditional menus.
We somewhat dodged a bullet in this regard. Apple and Microsoft both did experiments in component software back in the '90s, with Object Linking and Embedding on Windows and OpenDoc on the Mac.
They flopped for a variety of reasons, but one was the insane complexity of the UI: any object in a document was now potentially a mini application and had to negotiate control of the UI with other objects.
No ads. No pay wall. Damn I love man pages.
We should make information more discoverable by putting libraries on a single scroll, then it's just one single page.
It’s not.
I'm not saying we can't make CLIs more discoverable, but I simply hold the opposite opinion: They already win out over GUIs on discoverability.
I think they lose out on /accessibility/ to most users, unfortunately.
Say you need to remove duplicates from a list, for example. If you happen to know that the utility to do that is called `uniq` then it's useful that you can use `man uniq` to see the available options, but if you don't already know the name of the utility you're looking for, you're stuck Googling for it. (The name `uniq` isn't obvious but at least it's intuitive. For the many commands that are neither obvious nor intuitive, good luck.)
Compare that to, say, Excel, where if you press Alt,A to bring up the Data tab there's a nice, big button labeled Remove Duplicates, with an M on it to indicate that the full keystroke sequence for that command is Alt,A,M (fewer keystrokes than ` | uniq` even with tab completion, for what that's worth). So in addition to accessibility, there's also discoverability.
I've thought about this a lot. The answer, I think, is to have a "reverse index" of tasks that you can do with the tool and their corresponding commands or recipes.
For example, man pages are typically organized alphabetically by option or subcommand. I'm envisioning a section of documentation - maybe a separate man page or just something on a website - that looks like this (e.g. for rsync):
I want to ...
Transfer files within the local filesystem
rsync dir1/ dir2
Transfer files within the local filesystem & create a new directory
rsync dir1 dir2 # Note the lack of trailing slash on dir1
Preserve access times
Use -t/--times
Recurse into directories
Use -r/--recursive
< etc >
Such a document would be:
- Browsable and therefore discoverable
- Easy to search with plain text (can be optimized by making sure key words are inserted in the description text)
- A useful reference if you can't remember this or that specific incantation
You can
Get-Help Update-ItemProperty -Example
It is introspectable, so command line completion of argument parameters just work.
I even saw web based and windows based gui that can probe any powershell command and provide a rudimentary UI with field level help.
You can even find the relevant commands e.g.
Get-Command -Noun PSDrive
It still places some responsibility on the developer of the command line tool to expose a reasonable interface. But if they do so, users can learn the interface by tab-ing their way to glory.
The Google Cloud SDK (gcloud command-line tool) is a really great example of this. It was the first cloud infrastructure I worked on and I learned how Google Cloud worked by tab-completing gcloud commands and reading the --help pages.
AWS CLI is an example of when too much complexity is exposed to the user. They have similar tab completion functionality, but they provide such fine grained control that it is hard to use it to learn the services themselves.
Is this really a problem of CLI or just an example of a complex application? If we take for example something like excel or photoshop, then you can't easily figure what to do, even if the doc is directly embedded inside the UI.
> Back to discoverability, is there a way to make CLI "more discoverable"? Reading the man page doesn't count.
Why? It's an additional step, but can count as basic knowledge, similar to how someone needs to know how a mouse works and what the buttons do, before they can start using a GUI.
> Like can we combine the advantages of CLI with the discoverability of GUIs?
No, the moment you embedd the discoverabilty of GUI it stops being a CLI. TUI exist, and they do offer the same elements as GUI, just with less flexibility because text and so. But TUI serves a different purpose. You can't automate spatial interfaces as you can automate a cli. You need a dedicated way for allowing this, which is the main reason why CLI is so popular.
What you could do is defining many many APIs and protocols and guidelines, then define your interface in some generic way which allows you to automatic spin out a discoverable interface as also a useful automation-interface. But who wants that? That is extra work.
Similarly, how many people have trouble saving and quitting a word document? What about vim?
A command line interface can do with very little screen real estate. There's no reason GUI and command line can't coexist, with everything you do in the GUI immediately being reflected in the command line, and vice versa. This combines the context visibility and flexibility of a GUI with automatability and composability of a CLI. And you learn both at the same time.
That statement is falsified by the advent of programmable completions. Nothing stops us from integrating context sensitive help into the shell completion mechanism. The shell could display a help text next to each item of a completion list, or you could press keyboard shortcut to get help to the command your cursor is positioned on. shellcheck could highlight a bash command while you are typing it. All that would not change the fact that a shell is a CLI.
If you knew the command but not the flags then you could add the HELP flag to get more and more specific information.
See page 1-18 and 1-19 of the user guide: https://www.isis.stfc.ac.uk/Pages/vms-user-manual.pdf
We had a VMS cluster at college and I found it to be a very nice approach. Quite a bit better than man pages and a lot more consistent in my opinion.
Some of them had easter eggs tucked away in them of course, such as the Datatrieve Wombat: https://www.ibphoenix.com/resources/documents/history/doc_29...
In a sense, the help pages are a super-thin GUI on top of the underlying CLI.
I don't want to praise the Google Cloud CLI, but one nice thing is you can do something along the lines of
$ gcloud <tab>
-> list of services you want to manipulate
$ gcloud servicename <tab>
-> list of action you can do to service
$ gcloud servicename actionname --help
--> detailed information on how to apply that action
Finally, I think the architecture of man pages is all wrong: examples should always be primary, exhaustive descriptions of every little option are reference material and a last resort.
[0]: https://github.com/tldr-pages/tldr [1]: https://github.com/dbrgn/tealdeer
The first time I used Cisco’s IOS was pretty eye-opening to me, and I was thoroughly confused why something like that wasn’t present everywhere. (The only other place I’ve seen it is in MikroTik’s CLI.)
For those not familiar, at any point anywhere you can simply type a question mark and it will tell you all the valid inputs (commands, arguments, etc) at the exact spot your cursor is at and then put you right back where you were ready to continue typing.
You could discover a lot — not only what you were searching for, but related functionality — just by throwing a ‘?’ at it whenever you didn’t know what to type next.
Of course it helped that everything was named in a very straightforward manner. Something like this is never going to help you to discover a new Unix command because many are “cleverly” named. But once you find one you’ll be able to use it without ever referencing a manual page.
It may not scale to meta commands such as docker and terraform, though.
You’ll also need something to figure out which commands might help you do whatever you want to do. Apropos and locate help a bit there, but IMO need improvement.
https://pypi.org/project/howdoi/ is an attempt at that. I’ve never used it, so I don’t know how good it is.
In some sense, I guess stackoverflow is the best we have to make the CLI more discoverable.
The Docker and Git CLI both grew organically. Each new feature had to fit into the gaps between the old features without reusing the same terminology, and sometimes the easiest spot to implement something is not the spot you would first guess it should be. So it gets tacked on somewhere else to avoid coupling.
Rewriting an interface is difficult, and some people do it too often ('upgrade treadmills') or try to avoid doing it at all.
Although what situation are you in where a not-confident person is even using a CLI?
Is there a docker frontend for idiots like me somewhere?
I don't agree. Discoverability's a big problem with "modern" GUIs too.
> is there a way to make CLI "more discoverable"? Reading the man page doesn't count
Why doesn't reading the man page count? I've learned a hell of a lot more about CLI tools by reading their manual than I have by ... oh wait GUIs often don't come with a manual.
> I don't agree. Discoverability's a big problem with "modern" GUIs too.
Absolutely, nowadays you have to discover which part of the screen is clickable, you have to discover where they hid that stupid hamburger menu. The menus of the mac and Amiga were so, you could find them blindly with your mouse. On endless scrolling pages you often cannot skip ahead you have to scroll and wait, scroll and wait, scroll and wait, until the browser hangs.
[1]: https://www.man7.org/linux/man-pages/man1/apropos.1.html
I think that’s a design issue - what GUI element (menus, buttons, ...) is going to solve this in a way that couldn’t also be applied to the CLI?
--dns list Set custom DNS servers
--dns-option list Set DNS options
--dns-search list Set custom DNS search domains
--domainname string Container NIS domain name
--entrypoint string Overwrite the default ENTRYPOINT of the image
-e, --env list Set environment variables
--env-file list Read in a file of environment variables
--expose list Expose a port or a range of ports
You claimed man pages do not help. I disagree. To me man pages have the following advantages over web based documentation.
- A locally installed man page usually matches the version of the installed tool.
- I don't have to search for the correct web page or even software project that is the source of an installed program.
- It works offline.
- No SPA bullshit (hello docker and kafka) in documentation that slows down browsing, adds time wasting scroll animations, and often breaks navigation (Implementing the back and forward button in a SPA is not helpful if you loose your scroll state when navigating)
- Sometimes you have to use older software, i.e. because you want to recompile your college project with a matching compiler. Then it is really useful to have the documentation matching to your tools. Or you maintain certified firmwares, which were released and certified some years ago, then you have to use that software.
I am sure you are aware of the advantages of Web based documentation so I skip them.
update: [typos and formatting]
1. Get a better shell with good auto-completion. I find bash to be lacking in this regard. I use fish but others like zsh.
2. Use a helper command like `tldr`[1]. It's not perfect and certainly not a replacement for a proper manual page, but it helps when in the middle of work.
I've never read the manual for the GCP command line tools but I've used them extensively.
1. "The keyboard allows for faster input"; sometimes that's true, but consider picking a coordinate within an image. Mouse is better than KB for such a task. 2. Composable commands; GUIs have these too. 3. Scripting; GUIs have this too.
Reification in GUIs exists; consider an activity log or automator script. Absence of reification also exists in CLI; consider a package manager downloading packages; basically any CLI program that manipulates the screen like ncurses.
Which brings us to the worst offenders: CLI programs pretending to be GUI programs. They minimize the benefit of CLI while only taking the weakest advantages of a GUI. Build tools like webpack come to mind here.
The article seems to be presenting best-case CLI against worst-case GUI.
(Edit) Another example of reification is the Google Cloud Console, where you can go through a webpage for a complicated operation like creating a VM, but instead of pressing Save, you can click a link to see the equivalent gcloud CLI command and HTTP API request. I've used this a lot to script bulk operations after generating one outline for a request.
[0] https://docs.microsoft.com/en-us/windows-server/identity/ad-...
Taking not's of how to do things or creating shorcuts will also always be better with CLI's since manipulation text is easy and always supported.
Doesn't work everytime though.
On the other hand, a dialog assumes there's some value in the exchange of bits of information. In a general sense, GUI is a forum, allowing user to interact with several systems/components at once, as if constantly refining the common understanding of what needs to/could be/has been done.
I noticed a paradigm shift in GUI handling of settings dialogs. While traditionally there was an OK button to effectuate the changes, modern GUI assumes a more affirmative stance and effectuates each given change immediately, without the need for a final OK.
In a way this removes the program as a party in the dialog, making it closer to CLI interaction style.
Ultimately, we don't want to converse with the program/machine/system. We want the result, whatever it takes.
I'm not into chatting to bot/Siri/Google/Cortana/Echo/?? about turning on lights in the room. I'm commanding the lights. LIGHT!
I'm not convincing gmail to send a message for me. I'm talking to the recipient. Instead, I'm shown a progress bar, as if the program is asking me to cheer for it to reach the golden 100%.
I guess, deep down as user I'm more like 'command-and-control', rather than a receptive 'let's-hear-all-opinions' kind.
I “designed” the commands (the grammar, collected terms, syntax and semantics, etc.) before implementing them. The goal was to provide a “guessable” interface, eg. if you ‘load’ then it makes sense to ‘unload’.
Next time I do something graphical, I’d like to design a scriptable CLI interface first, then use end/entry-points to build the GUI.
- whitespace delimited with fields that contain whitespace.
- tabular lined up data that doesn't actually use tabs, and when a field is too wide, it just pushes the rest of the line over.
- 5,000 different variants of CSV
Of course some things (e.g. kubectl) have json and yaml output options, which can be nicely parsed with jq.
I also found https://github.com/kellyjonbrazil/jc handy, which attempts to convert many commands to json output.
E.g Most people today do not know that Autocad started using text commands for everything you did with your project(in DOS).
Those commands were interpreted in a dialect of Lisp(AutoLISP). First those commands were organized in menus, then text was replaced by icons, but the commands were there if you wanted to use them.
So you can use Rhino3d with both the GUI or the CLI. Or in blender3d, each GUI has a corresponding command you can use in Python.
Apple wanted to make it generic behavior for Apple apps with automator but most developers refused to make their programs scriptable.
Thinking about these 3 features together would essentially give a computer system a version control or tool assisted speed run kind of feel.
Every command changes the state, and the system can be rolled back, and experimented with.
I really like where this line of thinking could lead.
Docs: https://xerblin.readthedocs.io/en/latest/
Project: https://sr.ht/~sforman/Xerblin/
Repo (browse or clone): https://git.sr.ht/~sforman/Xerblin
I am in the process of adding more information to the docs. The code should run on a recent version of Python 3. The underlying language is Joy and the package for that is on PyPI so it should (fingers crossed!) download and install automatically if you run setup.py (I think). I'd appreciate any feedback you can give me. Ciao!
This could easily be used to document complex reusable command sequences.
Eg:
git quickref
This will list the most commonly used git invocations and their affect
Git quickref chekcout
This will list the most common checkout invocations.
Git doc open your browser to an offline doc html doc, etc