Easier onboarding

[Slackadays]

Is your feature request related to a problem? Please describe.
I want to use clifm, but it's confusing for me to get started. I don't know what's happening in the demo other than only 7 keystrokes being pressed. Also, I don't know what specifically clifm can do for me.

Describe the solution you'd like
I'd like the readme condensed and optimized to speed up 🚀 the onboarding process so that I and other users can get started with clifm easier. I don't know what the most important commands are so this would be a great addition.

Describe alternatives you've considered
There could be a simple tutorial section in the readme.

Additional context
I noticed that the readme is really focused on clifm's features and how it's all CLI. However, I don't know why this matters to me because CLIs are already great. Personally, I realized the same with clipboard and fixed it all up after watching this valuable video: https://www.ted.com/talks/simon_sinek_how_great_leaders_inspire_action/c

[leo-arch]

Hi @Slackadays. At the end of the README you can find a Getting started section, which, among other tips, points to the basic usage-examples page.

I'm not sure that's enough, or clear and simple enough: tips for making it better/simpler are welcome, of course.

Btw, I'll take a look at the video as soon as I can. Thanks for pointing it out!

[Slackadays]

@leo-arch Sorry for the really late response, but here's my list of tips for making it better/simpler:

• Move the Getting Started section to the verrry top because I only just remembered it was there when you pointed it out. Unlike us, most people only read the first few parts of the readme and get bored after that.
• Integrate the usage-examples section into the Getting Started section on the readme. You don't want users to have to click anything to get info, and I myself have left behind a couple projects because I had to click around to find information.
• Installation should be near the top just like Getting Started, and actually right behind that. Remember, you need to have clifm installed before you can get started using it.
• Provide a list of why you NEED clifm in your life. In that video I shared, the big takeaway is that good products don't advertise that they're good or why they're good, but rather why they exist for you. In CB's case, the main point is that it saves you time and effort to make your life more productive. Even though clifm might help with this too, nobody knows it because the readme never claims it does.
• This isn't a specific tip, but rather a general strategy for the whole readme. Try grouping things in three. Humans remember groups of three the best compared to two or four, so if you can make as many things as possible a group of three items, then people will be able to comprehend it better. See this other TED video: https://www.youtube.com/watch?v=o1jm-2WfTvk

[leo-arch]

Hey @Slackadays, no problem!

As to the README current arrangement, it's just a logical ordering (programming minds, you know), but maybe not the most psychologically effective ordering, that's true. I'll definitely bear your suggestions in mind. Thanks!

[Slackadays]

@leo-arch Looks like your star count is already increasing faster, so keep up this good work!

[Slackadays]

Another suggestion: Relegate the "privacy" claims to being a small detail somewhere in the documentation. Putting it front-and-center almost feels to me like going up to someone and saying, "Hi! I'm not a murderer." If you're making this claim for a CLI app, what else might be happening?

[leo-arch]

Hi @Slackadays. Yes, maybe having a privacy badge in the front page was a bit too much. I've removed it. Still in the features section though: these days, where analytics are integral part of lots of software's agenda, I feel it's important to let the user know we're not collecting data at all. Due to many reasons, I've become a security/privacy paranoid, and I know I'm not the only one.

Thanks for the suggestion!

[Slackadays]

Here's another suggestion I just remembered: See if the total number of assets in the root directory could be 10 or fewer. I don't know why GitHub doesn't try to keep them all tidy, but personally, I find it a chore when I have to scroll down a lot past the files list to read the readme. One great example of this done right is Howdy: https://github.com/boltgolt/howdy It has only 6. Clipboard has 8 which is about the bare minimum needed to not have to create a build directory manually.

[leo-arch]

Now that you mention it, there are a few files in the root directory that could be just removed. However, I'm not sure I'll be able to cut it down below 12 files.

[leo-arch]

Yeah, 12 files (4 removed). Not bad.

[Slackadays]

Nice!

[Slackadays]

This is kind of huge suggestion, but an important one. I looked through the code and it's chock-full of one-letter variables and funky tricks that I believe might be preventing more PRs from flowing in. If possible, would purging all one-letter variables be a viable option? Maybe something more descriptive unless it's a classic i or j for loops.

[leo-arch]

Hi @Slackadays. I'm fully aware that there's a lot of room for improvement.

As to one-letter-variables, I try to use them only in really short blocks or functions, mostly when we don't lose visual track of the variable. However, I'll take a look at it and bear you suggestion in mind for the future.

As to "funky tricks", what do you mean exactly? Can you please refer to some specific piece of code?

[Slackadays]

I think maybe "tricks" might not have been the best word, but maybe "dense." It's lines like this one

clifm/src/readline.c

Line 3193 in 8f28aaa

if (tags_n > 0 && *text == 't' && *(text + 1) == ':' && *(text + 2)) {

which have a lot of dense logic combined with those one-letter variables and pointer symbols which might make clifm look unappealing to those who want to help contribute.

I know this might seem nebulous, but I just think more descriptive code will help others feel more attracted to the codebase.

[leo-arch]

Well, maybe you're right. I just tend to avoid calls to strcmp(3) when it is possible to replace it by a few byte comparisons (like in this case) for performance reasons. Secondly, I prefer (and this is just a personal preference) pointer notation over array notation, though this latter might be more readable.

Maybe you have in mind something along these lines:

if (tags_n > 0 && strncmp(text, "t:", 2) == 0 && text[2])

Isn't it?

[Slackadays]

@leo-arch That looks a whole lot better already! If you're using that kind of pattern a lot, then it might actually be worth it to make a wrapper function that looks good to call and has the optimized logic underneath so you can have your cake and eat it too. I'm more used to the C++ versions where you can just use == and substr() but this C version is already a huge improvement over before.

[leo-arch]

I still prefer to avoid calling a function when it is not necessary, So, maybe just removing the pointer notation makes this line look a bit better:

if (tags_n > 0 && text[0] == 't' && text[1] == ':' && text[2])

Be it as it may, I do know what you mean: some lines (and even whole functions) tend to be dense and cryptic (far worse than the one you quoted). Agreed. Refactoring code is something I've been doing since the last year at least: but, yes, there's still a lot of work to be done.

[leo-arch]

As always, thanks for your suggestions @Slackadays!

[Slackadays]

When do you think we should close this? I think this might always be an ongoing "issue" but we've already done a lot so far.

[leo-arch]

Hey @Slackadays! Well, technically this is a never-ending issue. So yes, feel free to close it. You can reopen it any time, of course.

[Slackadays]

@leo-arch This sounds grrreat! However, before doing so, here's a couple more suggestions to help the readme attract even more new users:

• Purge the Table Of Contents because of the recent cleaning up. Now that each section has a clearly visible title and is "in the correct order," users can just go from one section to the next without needing to look at the TOC. Therefore, the TOC is adding extra mental load which could scare some away.
• Rephrase the "Contributing" section from "Yes..." to something like "We love your contributions..." so that contributors feel more welcome.
• Provide what keystrokes you need to select all the images in the demo photo, because it's not that obvious just by looking at it. For example: We only need 7 key...directory: keystrokes here
• Simplify the formatting of the sections like Contributing and License so that each sentence isn't on a new line. Personally, I feel like although this is a minor detail, it helps keep everything in line, with the other direction being to put a full break between the sentences. For example, in

  clifm/README.md

  Line 325 in 7a9c701

  This project is licensed GPL version 2 (or later). \

  
  remove the \, or add a full break between the lines.

I just want to help clifm be as great as it can to as many people as possible. :)

[leo-arch]

What about now? Shorter, leaner, straight to the point.

[Slackadays]

It looks fantastic! I actually forgot you removed the TOC when I read the latest version because the other content is now too well made to need it. 🚀

[leo-arch]

Thanks for your suggestions Slack, as always!

[Slackadays]

@leo-arch Something else you could do is to add good-first-issue as a topic to the repo, as that'll reveal clifm to anybody looking at https://github.com/topics/good-first-issue to find projects to contribute to. However, I've heard reports of this attracting low-quality submissions, so I'm unsure how this might turn out.

[leo-arch]

I'll take a look at this good-first-issue thing Slack. Thanks for the suggestion.

[Slackadays]

Another suggestion I have that might get clifm more attention is to make the releases more frequent. Right now, it looks like each release has a laundry list of additions/bugfixes, and waiting until you have another laundry list is leaving potential eyes looking at them on the table. If you keep going at the same rate of development then it seems like a new release every couple weeks might be viable. One piece of advice regarding this from the author of SumatraPDF is to make a new release as soon as you make a user-facing improvement. :)

[leo-arch]

Hey Slack, thanks for the advice! Yes, currently I have no fixed rules for when to make a new release: It's not that I'm waiting to have an enough long list of fixes/improvements; I just wait to feel that new features are mature, that they won't break anything (but it's just a feeling, you know; I test everything as much as I can, considering also bug reports, but you can never bu sure). So, I'll consider the user-facing-improvement rule.

Another thing I was thinking is about pre-releases: I bump the revision version about 2-3 days. Maybe I should make a pre-release for each of these versions. However, this approach won't face the potential-eyes-looking-at-bugs issue, for pre-releases, as far as I know, aren't meant to be packaged.

I'll keep thinking about it.

[Slackadays]

Here's another idea for more users: make a website. GitHub Pages works great with the Zola static site generator and that's what we used for CB here: https://getclipboard.app/

In that case, we also picked out a nice looking template and filled in the relevant info. Right now, it looks like clifm just has the Wiki as the website which isn't that good for discoverability. However, a real full-fat site would be exactly as good as you want it to be since you're not constrained to markdown or the GH platform. The result will be a bigger "presence" since you now have your own place to call home.

[leo-arch]

Hey, looks cool! I've been using Github pages for a while, but the generated site is currently broken. I'll take a look at Zola as soon as I have some time to work on it. Thanks Slack!