3 ms·
> 1. Great help is essential I like how this is their #1. In my opinion the best way to do this is with tldr. https://github.com/tldr-pages/tldr https://githu
by breckuh 8y ago
> 1. Great help is essential
I like how this is their #1. In my opinion the best way to do this is with tldr.
https://github.com/tldr-pages/tldr https://github.com/tldr-pages/tldr
I'd highly recommend folks create a tldr page for their CLI app. Add 4-8 examples to cover 80%+ of the most common use cases. -h flags, readmes & man pages can cover the other 20%.
- dickeytk 8y agoI almost want to rewrite the help section to encourage examples even more. They're incredibly valuable. I hadn't considered this before you mentioned it, but oclif CLIs could integrate to tldr pretty well. It already supports arrays of strings for examples.
- tetha 8y agoYup. On CPAN, it is encouraged that the first part of your documentation after the table of contents is the synopsis[1]. The synopsis should clearly show how to do the common tricks with the library. From there you can link and refer to the more detailed documentation. We're doing that for our internal CLI applications and it's great to be able to just copy-paste the common use case from the top of the documentation without searching much. 1: https://metacpan.org/pod/Carp https://metacpan.org/pod/Carp
- dickeytk 8y agoI feel the synopsis section of man pages often just becomes a bunch of useless garbage above the fold (for instance, look at `man git`). Using it less as a complete docopts kind of thing and more of multiple common usages (like `man tar` and what you linked) is far more useful. I think there is something here I hadn't really considered before. It's not an example, but also not a useless dump of flags. Food for thought I suppose.
- Riverheart 8y agoAgreed on making examples more important. Powershell, for example, let's you "get-help command -examples" to just retrieve those.