Hacker News Reader

Comment by breckuh | Hacker News Reader

> 1. Great help is essential

I like how this is their #1. In my opinion the best way to do this is with 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%.

View on HN

I 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.

Yup. 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

I 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.

Agreed on making examples more important. Powershell, for example, let's you "get-help command -examples" to just retrieve those.

Reply on news.ycombinator.com