4 ms·
is there a way to make CLI "more discoverable" I've thought about this a lot. The answer, I think, is to have a "reverse index" of tasks that you can do with t
by nerdponx 6y ago
is there a way to make CLI "more discoverable"
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 >
You can construct a lot of interesting recipes in this format. Rsync, Make, Find, Git, Docker, and many others all could benefit from this kind of treatment.
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
- pritambaral 6y agoIsn't that just the EXAMPLES section of a man page?
- sedatk 6y agoYes but not all CLI tools have it, or have it extensive enough.
- gindely 6y agoBut then the solution is just "better documentation". Every time the solution is just "don't suck", i think it's fair to say that the solution won't work. For instance, in the past decade or so, the quality of guis have gone so far downhill, that is now commonplace for advanced users to have no idea that certain features exist because they're only exposed if you swipe like so and then tap this logo that doesn't look like a button. the technical knowledge exists for how to design usable graphical user interfaces, but "make better UIs" is not a high priority for businesses and the people they hire. cli's have a certain advantage that many cli's are open source and technically not beholden to business interests (altho they may be defacto), and they're not fashionable amongst those for whom empowering users is a curseword, so "don't suck" is theoretically possible, but i don't know that it's particularly likely.
- nerdponx 6y agoSort of? Most "examples" are just scattershot random functionality that the author deemed important, with little consideration for actual use. GNU Parallel is a notable exception, albeit a somewhat disorganized one.
- aastronaut 6y agoI use tldr[0] for that. [0]: https://github.com/tldr-pages/tldr/ https://github.com/tldr-pages/tldr/
- teyc 6y agoPowershell has a common language, common help system, common logging framework. It's a very nicely done project. You can Get-Help Update-ItemProperty -Example to get some samples. 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 gets you all the commands that can act on a PSDrive object.
- nerdponx 6y agoThis is really useful, thanks for that. Unfortunately I can't bring myself to use Powershell because of the sheer verbosity of the command line (might as well just use Python, in my opinion), but I really like a lot of their design choices.