Standardize the project description

[waldyrious]

Following up on #1109 (unifying the name of the project), I'm putting forward a proposal to unify the project description as well. Currently we have at least three variants:

• "Simplified and community-driven man pages" (in the repo description and the website sub-heading)
• "A community effort to simplify the beloved man pages with practical examples." (in the website description)
• "A collection of simplified and community-driven man pages." (in the README file)

I'm proposing "A community-curated collection of simplified and example-driven man pages." which is combines the best aspects of all three IMO. The goal is to use the same phrasing everywhere, kind of as a slogan.

Any thoughts? I'm wondering about "curated" (maybe "maintained" instead?) and "example-driven" (maybe "example-based" instead?).

[agnivade]

"A community-curated collection of simplified and example-driven man pages." is too big for my taste if we are planning to use it as a slogan.

I think the main problem is with "community-curated". I am good with just "curated". Similar to the awesome lists. They also mention "curated".

"A curated collection of simplified and example-driven man pages." feels much better.

[waldyrious]

I think the "community" aspect is way more important than the "curated" part. Do you think there could be a way to rephrase it more concisely while preserving the community focus?

[leostera]

I personally think we can't get much more concise than

Simplified and community-driven man pages

And any attempt at reducing it's length further down would imply a change in meaning.

HOWEVER, I can see the the Simplified dropping, and using only

Community-driven man pages

Maybe even

Community-curated man pages

Of course this is just the tagline. It needs to be have a punch. And as @waldyrious says, it needs to emphasize the community around it.

Right below this, the whole description of the project makes more sense as (like @agnivade champions)

A community-curated collection of simplified and example-driven man pages

---

Now if you wanted to go all Mad Men on it 😂 :

man pages for the layman

[sbrl]

I think that something to emphasise the simplified nature of the tldr-pages is also important

[waldyrious]

Revisiting this issue, I think the main traits we should emphasise are the simplicity, as @sbrl says, and the community aspect as I mentioned above.

The fact that the tldr-pages are example-based is kind of subsumed in the "simplicity" part, and we can always describe the project in prose in the README and elsewhere. The community-driven, community-curated, etc. can be neatly contained in the adjective "collaborative", which hopefully overcomes @agnivade's concern with the wording of that aspect.

With that in light, what do you guys think of the following?

a collaborative collection of simplified man-pages

I also like @Ostera's proposal

man pages for the layman

which is reasonably descriptive and catchy, so would work well as a slogan, with the first one then incorporated in the extended, free-form description.

Can we pick one of these two, or do you suggest something else? I would be fine with either of these, although I'm tending to slightly favor the latter.

[agnivade]

I favor the first one. But can we add the word 'curated' please ? That gives the impression that the content is specially tailored.

[waldyrious]

We can re-introduce "curated", sure, but I wanted to avoid a less common word, and shorten the description as much as possible. But mainly, I confess I'm a little puzzled by your comments in this thread regarding the word "curated" -- why do you think it's important convey the notion that the project's content is specially tailored? Also, specially tailored to what, exactly?

[agnivade]

But mainly, I confess I'm a little puzzled by your comments in this thread regarding the word "curated"

Haha, sure. I love the "awesome" series of repos, if you are aware of them ? All of them have the word "curated". https://github.com/vuejs/awesome-vue, https://github.com/avelino/awesome-go. I kinda like that. Hence this preference.

I hope it's not not too uncommon a word. It's okay if you think it stretches the description too much, we can drop it.

[waldyrious]

I do know the awesome series of repos (I've created one myself :)), and I understand why they use the word "curated" — to mean that there's a deliberate selection of items that are considered awesome, i.e. standing out from the rest, rather than being merely lists aiming at complete coverage.

In our case, we do have curated content within the pages themselves (we follow the philosophy of providing a representative usage sample, rather than a comprehensive reference, and the 8-example limit enforces this in practice), but crucially, we don't exactly curate which pages are included in our list — quite the contrary: we do aim for complete coverage of items included.

This means that, yes, each page can be described as a curated set of examples, but the list itself (which is the focus of the description we're discussing in this thread) is not a curated set of pages, in that sense of "curated".

Now, we could assume the meaning of "curated" as "carefully collected and maintained", but I'm afraid the potential for ambiguity, plus the uncommonness of the word for non-native English speakers, does not justify its use. But as always, happy to consider arguments to the contrary!

[agnivade]

Fair enough. I withdraw my objections. I go with the first choice then !

a collaborative collection of simplified man-pages

[waldyrious]

That's great to hear, thanks for understanding. Waiting for @Ostera and @sbrl to comment, then.

[sbrl]

My vote is for a collaborative collection of simplified man-pages.

[waldyrious]

You guys are no fun :P let's wait for @Ostera (and maybe @rprieto) for the final tally.

[rprieto]

Great discussion. I like the collaborative collection part, but not sure if simplified man pages reflects the truth. I think this project aims to complement man pages with concrete usable examples (given the absence of examples in most man pages, and the high-barrier to contribution). What about a collaborative collection of CLI examples to complement man pages?

[waldyrious]

Well, the standard manpage format does prescribe an (optional) "EXAMPLES" section that pretty much covers the same ground as we do here,^† so I'm not sure we can be considered complementary to man pages other than the fact that many manpages lack that section, which is incidental, rather than deliberate.

So in my view it's neither necessary nor accurate to include a note on such complementarity — in fact, in a perfect world where all manpages did include an EXAMPLES section, tldr pages would be precisely pared-down (i.e. simplified) versions of manpages, containing only the (possibly shortened) contents of that section :)

_{† In fact, those are probably a good source of low-hanging fruit for missing pages — something to keep in mind in #1070.}

[waldyrious]

That said, I do get the appeal of mentioning "examples" rather than merely "simplified". My only concern is making the short description not so short after all, hence my proposal to have a quick slogan-like description, with a more detailed (say, a one or two sentences) in the README, home page, etc.

Or we could go full descriptive and less evocative, dropping the reference to manpages entirely:

collaborative collection of usage examples for command-line tools

(which, again, I find perfectly cromulent, but much blander than @Ostera's punny "man pages for the layman" :P)

[waldyrious]

Maybe we could re-introduce some fun with a little alliteration 😛

collaborative collection of common (use) cases for console commands

Or maybe even better:

collaborative collection of compact cheatsheets for console commands

[leostera]

cromulent indeed, good sire!

Hello everyone, I’m late to this too. My half øre (because two cents is too mainstream) would be to go with something that has pizzazz.

I like the alliterations! I do indeed. So in order of preference:

1 - self vote.
2 - alliterations.
3 - other more specific and less playful alternatives.

My reason behind this is that even thou we may be serving experienced but forgetful users, we are still aiming at the newcomers, and the last thing newcomers need is another RTFM.

Being playful and maintaining quality is a hard balance to keep, but so far we’ve done great work on curating these pages. Don’t see why we couldn’t try and check how the numbers do...after all Any rebranding is done to increase awareness and pull the brand value up ☝🏼

[leostera]

s/ he last thing/ the last thing

Can’t edit on GitHub for mobile?! Outrageous!

(ノಥ,_｣ಥ)ノ彡┻━┻

[sbrl]

I do like collaborative collection of compact cheatsheets for console commands a lot too!

[zlatanvasovic]

Still not resolved. Both A collection of simplified and community-driven man pages (also with A and without it) and simplified and community-driven man pages are present.

I would go with the second one to end the branding issue and go on. It's simple and effective slogan, it simply works.

[zlatanvasovic]

Once #1109 gets closed, this issue can be closed aswell.

[waldyrious]

@zdroid I'm not sure that's the case. That issue is about the project name, while this is about the slogan / short description. But I do agree we should make a push to get a final decision in both! 👍

[zlatanvasovic]

#3657 and #3724 resolve the issue of outdated description in the documentation. It's still the other way in @waldyrious's banners from 0e8cbca.

But I have to say, collaborative collection of compact cheatsheets for console commands catches the attention quite well.

[waldyrious]

Is anyone actually opposed to collaborative collection of compact cheatsheets for console commands? I get that it's playful, but not in a way that detracts from its clarity; in fact, I'd argue that it's better than the current one regardless of its fun aspect: it's even more explicit and informative than simplified and community-driven man-pages, and the fun part is just a bonus. Here's why:

• "simplified" doesn't mean "short", but let's grant that one as a given, especially because we use the latter only as a proxy for the former, which is our real goal;
• "community-driven" is a close synonym to "collaborative", but longer;
• "man-pages", while paying homage to the venerable original source of documentation for commands, requires prior knowledge/background which may not be as common today as it used to be (as many CLI tools nowadays come with their own --help output and no manpage)
  • In fact, "cheatsheets for console commands" describes exactly what this project is, while the "man pages, but simpler" approach we use now starts from what it isn't. Granted, using a point of familiarity to introduce a new concept is useful, but on the one hand, as I mentioned above, familiarity of manpages may not be what it was, and on the other hand neither cheatsheets nore console commands are novel concepts anyway.

If you're worried about the length, I think we could shorten it without loss of meaning:

• "collection" is arguably redundant with the plural in "cheatsheets"
• "compact" is somewhat implied by "cheatsheet"

...which would lead us to collaborative cheatsheets for console commands, which IMO is just as informative (albeit less playful), and still better than the current one. Let me be clear, by the way: I don't think we have a bad slogan at all! I just think we could do even better :)

ps - This is anectotal, but despite never using the Flux.jl package myself, I never forgot its clever slogan "Relax! Flux is the ML library that doesn't make you tensor." — a catchy slogan goes a long way in making an idea memorable (which is why I argued for !

_{pps - Actually, if we want to go all-in in the communal aspect of this project, we could shorten the description to "collaborative cheatsheets for console programs" which would make an implicit acronym CCCP 😛 (just kidding!!)}

[zlatanvasovic]

I say we roll with collaborative cheatsheets for console commands.

[sbrl]

@waldyrious Ah, I quite liked that one! Both variants would be fine by me :D

[waldyrious]

@Ostera, @agnivade, any thoughts? This seems compatible with your comments above :)

[agnivade]

I am fine with the shortened one, but I am wondering whether "cheatsheets" are a good idea for the description. Several times, in our reviews, we have mentioned that this project is unlike other 'cheatsheet" like project where various combinations of commands are just dumped without a specific order to build them. Won't that conflict with the idea that we have now cheatsheet in our description ?

[waldyrious]

Fair point. While "cheatsheet" may be interpreted in ways contrary to our mission (e.g. including contrived, code-golf-esque hyper-compact formulations, or featuring rare use cases or clever tricks), I still feel it's closer to "short list of common usage examples" than "simplified manpages". Ultimately, a manpage is a reference manual, and only a small portion of it (the EXAMPLES section) matches what we provide with tldr-pages. And many manpages don't even feature those.

So my perception is that we were using "manpages" in our description mostly based on them being the primary/default source of help content for CLI tools, which, as I mentioned above, is no longer true.

If it helps, I'd suggest adding the actual description of "short list of common usage examples" right at the top of the README, in the What is tldr? section, before the tar narrative.

[sbrl]

Let's go with the shorter one of the 2 then :-)

Yeah, that's a good idea too @waldyrious. Though I think that we shouldn't drop the comparison to man pages completely though, because it's a common frame of reference we can use to get our point across more effectively.

[agnivade]

Sounds good.

[waldyrious]

Though I think that we shouldn't drop the comparison to man pages completely though

Of course -- let's keep it in the README and wherever else it makes sense (especially since we still have "pages" in the project name). I was just referring to the slogan.

I'll open a PR making the change to collaborative cheatsheets for console commands, once #4035 is merged.

[agnivade]

@waldyrious - Now that #4035 is merged, is it in your radar to send the PR for the description ?

[waldyrious]

Yeah, that was the plan :) I should be able to send the PR later today.