Add a short "Quick Start" section to the README for common actions

[VNel]

While the README already points users to man htop and the built-in help for a complete list of commands, it currently does not contain a short, immediately visible overview of the most commonly used actions.

For new users, it could be helpful to add a small “Quick Start” section directly to the README that lists a few frequent actions such as:

• searching / filtering processes

• sorting by CPU or memory

• switching to tree view

• killing a process

This section would not replace the manual, but complement it by giving beginners a quick entry point before referring them to man htop for full documentation.

Definition of Ready (DoR):

• The scope is limited to a small README addition

• No functional changes to htop itself are required

• The content focuses only on common default actions and keys

• The full manual (man htop) remains the primary reference

[Explorer09]

Why do we need this? It sounds as if the in-app help screen is not enough.

Or, sorry for asking, is this information meant to feed some AI engines that would spit quick helps for users that are too lazy to read the help screen at all?

P.S. My concern is about, what are the criteria for an action to be "common" so that it deserves a special attention in the documentation. I believe users using htop would not just want to kill processes. There are other use cases such as changing nice levels of processes, tracing system calls of a process (if compiled with the optional ptrace support). The user might also just want to view CPU and RAM usages in fancy bars. So it's not just one or a limited uses of the htop app.

[BenBE]

Not even that. If someone is too lazy to read half a screen of available actions, I genuinely doubt they’d bother reading the prose in the README. And even looking at the suggested list, there are things missing, like navigation, configuration, or exiting the program. That said, I don’t believe our users are that lobotomized, so I’m confident they can manage without this change.

[rubyFeedback]

Why do we need this? It sounds as if the in-app help screen is not enough

I started to use htop back in 2005 or so when I found GoboLinux. htop was part
of GoboLinux; hisham was quite active back then. Nowadays he is very lua-creative.

I kind of explored htop "naturally" via in-app only, that is, I would usually have htop running
in a konsole tab (last one usually), or yakuake. I never read any man page or anything for
htop, so my knowledge is actually limited. In the app one does not necessarily find everything
or learn everything. Some things I actually read about in github issue trackers, then tried
them out. :)

feed some AI engines that would spit quick helps for users that are too lazy to read the
help screen at all?

AI slop will do its own thing at all times anyways.

What I have noticed in the last months is that the documentation of many open source
projects has gotten much, much worse; I think it was bad even years before, but I
did not notice it, for many reasons. One reason is that Google search used to be
better; now it is also crap. I can not find much at all.

So, based on my own experience here, I am all in favour of better documentation in
general. I noticed this with regard to ruby projects, for instance, "rack", has barely
any documentation - after almost 20 years. Nada. Just some autogenerated API
documentation that is virtually useless.

That does not necessarily validate BenBE's suggestion, or invalidates it - mind you. I
am just adding a general remark as to documentation and why it is very important
now, with the rise of AI crap in general. This in part also relates to structure of
e. g. the main README as a general entry-point. I have no particular preference
here, mind you - just that we are able to find documentation when possible,
and ideally to have it all contained in the same project. (jruby often used to have
external links, but these died, and now the information is lost; this is why I think
documentation should ideally be as self-contained as possible within a given
project.)

We should also ask the young folks these days how they find htop and the
documentation. I am no longer among the young folks; back then I think I
accidentally just found GoboLinux and went from there. Nowadays people
use computers differently, many smartphones everywhere and so forth - perhaps
we can distil this into a useful primary entry point towards htop. For instance,
while I do check here every now and then, I don't quite know what features
are new. I actually use everything within the app whenever possible, but I
would not mind high quality documentation, tutorials and examples.

what are the criteria for an action to be "common"

Good question, I can not answer this one. Perhaps we could make a poll or something
like that, in particular from the point of view of new users. As an old user myself
I find it hard to notice which parts of htop may require improvement or better
documentation. Perhaps new folks to htop can share some insights from their point
of view.

[Explorer09]

@rubyFeedback I think a better path to start improving documentation is to rework the help (F1) screen, especially on the key action descriptions. For now they are just listed as a unordered list without any grouping. If we group the key actions by the use cases (example grouping could be: navigation, change view, kill/manipulate processes, miscellaneous), then the help screen can improve greatly.

[natoscott]

Some new users first interaction will be the man page, some will go the interactive-tool-use route, and others still will cast an eye over the README. All of these contact points can be improved. We don't get to tell people what to do first, it happens organically.

So, the suggestion look good to me - very short, very simple primer that quickly entices a newbie into getting started exploring further. Just like it says on the tin. 🚀