Should we allow more than 8 examples?

[mfrw]

@sbrl @waldyrious @agnivade @mebeim certain pages are already kind of full. How should we prioritize what 8 examples stay and what don't?
Also, does it make sense to break the rule of 8 examples, if the utility is useful?
e.g: #2798

[waldyrious]

This has been discussed several times if I recall correctly; the thread that originated the current limit was in PR #1149. You may also find relevant remarks if you search for "commandlinefu".

What we've repeatedly agreed is that the main purpose of the tldr-pages project (it's in the name!) is to provide a short summary, and never exhaustive coverage of the tools. This is even item no. 1 in our guidelines:

Try to keep pages at around 5 examples. Pages can be longer if needed, but don't exceed 8 examples. Remember, it's OK if the page doesn't cover everything; that's what man is for.

Of course, for more complex commands this will be challenging, but it is a challenge we should embrace to help us formulate the most concise quick-start for each tool. In fact, the most complex tools are precisely the ones more in need of a quick intro resource.

How should we prioritize what 8 examples stay and what don't?

I'd use the 80-20 rule here: even if what we can cover in a tldr-page is only about 20% of what the command can do, we can strive to cover the 20% most common invocations that will cover 80% of the use cases.

Additionally, we can balance that strategy with one of picking examples that illustrate the tool's usage in composable ways, so that people can use the tldr-pages examples as building blocks to figure out how to build specific more complex invocations they may need.

So rather than offering complete, ready-made examples that can be used directly, we should leave that goal to commandlinefu, and instead focus on "teaching users how to fish" by making short guides that explain how each tool works.

[mebeim]

I agree with @waldyrious.

I think focusing on having a short and useful set of most common examples to get started with a command is the main goal. Eight examples already feel like enough for that purpose. If a command is more complex and requires more than just a TLDR page, then there's man that can answer all your questions.

TLDR is for when you're in a hurry or when you need to perform a trivial task, but you don't remember the syntax of the command. More complex commands could also use examples that combine multiple options to create a more complete page, as already said.

Taking #2798 as an example: most of the examples in the file proposed in that PR are actually kind of redundant, and some are not as commonly used as others. In such cases I think we should carefully analyze which one makes more sense to be in the page and which one doesn't.

[agnivade]

Yeah, in the past, we have always asked the PR author if he/she is adding a new example which exceeds 8, to carefully analyze if the new example is more important that all the existing ones, and then to remove the one which is the one least likely to be used.

I think it is good to remain within the limit of 8 so that people get a brief overview. The core idea is not to become the man page itself, but a easy and practical introduction to it.

[sbrl]

You can always write your own longer cheat sheet for a command if you find yourself using it a lot and needing less-common use cases often :-)

[mebeim]

Oops tagged @agnivade in the previous comment but actually meant @waldyrious, my bad :')

[waldyrious]

You can always write your own longer cheat sheet for a command if you find yourself using it a lot and needing less-common use cases often :-)

That reminds me: we have in the past considered more elegant ways to handle multi-platform commands than what we currently have (duplicated content that sometimes goes out of sync), and a potential solution could also be used for custom user extensions.

Imagine e.g. command foo that exists for macOS and Linux; we could have common/foo.md with the examples whose syntax is identical in both systems; then linux/foo.md would have only the Linux-specific content, that would get appended to the contents of the common/ page, and so on.

With such a system in place, it would be trivial to extend it to also support a user/ or local/ directory, with extensions that would be added to the regular tldr output, rather than completely replace it.

If you guys think the idea has merit, perhaps we could repurpose this issue to discuss such a page extension mechanism.

[agnivade]

Appending to the end of the page has its risks. Sometimes the examples need to be in the middle or at the top depending on their order with the rest of the page.

[waldyrious]

Good point. I can't think of a good solution to that. Besides, even if we solved that problem, such an approach would mean that the complete page would not be available anywhere in the repo; the only way to access the composed page would be via clients, which kinda defeats the human-readability purpose of using markdown.

[sbrl]

The other issue is that in some cases, we want to remove an example when copying to another platform's page rather than add to it.

Also, you may be interested in #2706 @waldyrious. Fair warning: The conversation there is rather lengthy! I'd suggest reading the changes themselves and the ~3-4 comments.

[waldyrious]

@sbrl rest assured, it's on my radar, but I've been having a hard time blocking out significant chunks of time to handle issues in this project (other than small stuff here and there). I'll do my best to tackle that and others soon, but I don't have a specific time-frame I can promise, sorry :(

[sbrl]

No problem, @waldyrious :-)

[zlatanvasovic]

Reopen this, yes/no?

[mebeim]

@zdroid why? I thought we all agreed that 8 was ok as a limit for the number of examples.

[zlatanvasovic]

Because of #3718. I am not saying this has to be reopened, just that maybe a reason for that exists.

[mebeim]

@zdroid yeah I've seen #3718, I don't believe that warrants an upgrade in the number of examples. ffmpeg is a very, very complicated program, it's impossible to cover most common usages even with double the examples. It's a matter of choosing which ones are the most useful IMHO.

[owenvoke]

I have to agree with @mebeim on this. It's been discussed previously, and I think 8 is fine. 👍

[mmahmoudian]

After searching in the issues I finally found this thread.

I understand that for the majority of commands and CLI applications, the 8 is enough, but for certain software, it seems necessary. So I propose a solution (middle-ground) here:

Solution

I propose adding an argument -e, --extended which loads more than 8. This gives the users the freedom to choose how much they want to see.

Implementation suggestion

This can be very easily implemented using one of the following strategies:

1. Storing everything in a single file. When the flag is not given, only the first 8 is loaded, when the -e is provided, it loads the whole markdown. When using this method, the "extended" commands can also be added below a horizontal line. I personally believe the horizontal line is not necessary, but it can improve human readability.
2. Storing in separate files. This way the "extended" commands can go ina subfolder (e.g tldr/pages/linux/extended). When the flag is given, the normal list and the extended are concatenated and shown to user.

[sbrl]

Interesting concept, @mmahmoudian. However, commands that need more than 8 examples to document them may be better served with longer cheat sheets of their own. Commands that come to mind that might fit in this category include awk, sed, etc. Commands with many subcommands can still be documented effectively in tldr pages by giving each subcommand it's own page.

[mmahmoudian]

@sbrl thanks for considering the suggestion and being open to new ideas even in such closed issues.

I of course I'm not trying to push my opinion and I'm just trying to pitch a suggestion as clearly there are quite a few people (including me) that believe it would be nice and even somewhat necessary to have more than 8 items.

I've been using tldr for about a year, and I didn't know that tldr supports separate pages for subcommands! And I bet the majority of tldr users are not aware of it either. Where can I fid documentation for it?

Some additional commands that I think can really use more than 8 are rsync, pacman (and any pacman-like aur helper like paru) grep, nmcli, and ImageMagic commands (esp. convert)

[marchersimon]

I've been using tldr for about a year, and I didn't know that tldr supports separate pages for subcommands! And I bet the majority of tldr users are not aware of it either. Where can I fid documentation for it?

We're about to fix this issue in #6383

Regarding more examples for e.g. sed, I personally wouldn't be opposed to adding more examples. The rule that we only have 8 examples is mainly to keep simple commands simple so that the page doesn't get too long and confusing.

If we manage to keep all examples on their own simple I think it can't hurt to have more of them. @sbrl what do you think?