I almost can't believe I'm saying this because I really like the idea that people looking at documentation get exposed to more background and context, but here goes...
Since the beginning, the list of ACME clients has been organized by the language in which the clients are written. However, this information is most useful only for people who themselves plan to further develop the clients' functionality, or integrate the clients into some larger software environment.
I thought of this because there is the kind of anomalous "Windows" category, which is not about what language clients are written in (C#, Powershell, Python, or whatever), but about the fact that they're capable of running on a particular operating system (in this case, an operating system that is less commonly used for servers...).
The patterns of forum questions here suggest to me that most new users are more interested in other details about clients, perhaps like
What operating systems do they run on?
What web servers do they integrate with?
What DNS providers do they integrate with?
Do they support automated renewals?
Do they require administrative access?
and also occasionally for some people things like
Do they work with shared hosting without cooperating from the hosting provider?
Do they have a CLI, GUI, or remote web interface?
Do you have to pay someone to use them? Do they have official paid or unpaid support?
Are they under a free or proprietary license?
Are they still actively being developed?
We're very often telling people who are new to Let's Encrypt that they'll need to choose a client, but it seems like essentially the only thing the client list page is telling them is "Certbot is recommended, and then here are all of these others, with the programming languages that were used to create them".
It might be a somewhat politically touchy thing for ISRG to do, but I feel like a lot of users would probably even appreciate seeing "These are the top 10 most used clients today" or "The results of an informal survey on the Let's Encrypt Community Forum said that these were the top 10 most widely recommended clients" or something. Or "Here is an 80-character summary from the developer of each client about the features/intended audience of each one".
I agree on most every point you've made @schoen. Selecting a client is almost like choosing a car model. Some people have really done their research and know what they're after. Most probably just default to certbot. If they're Windows users they go with one of the only three that seem to have any real usage (and only two I have any confidence will have consistent support). If not, then they either go with what they have at hand from the host/platform/whatever (think Bitnami/lego) or come here and ask what to get. Honestly, I feel like the majority of clients are either so niche that you either use them or you don't OR no one uses them (unless somehow they just happen to work so well that we never hear them mentioned in the community).
I think it should probably be separated into a few pages to be honest, or at least make a beginner page separate from the rest where you can just download a client which will fetch you a certificate. Something like,
Beginner - User friendly clients / I just want a certificate already
These are what people can download to directly get a certificate, eg: certbot, acme.sh. You do not need to compile anything, or at the very least binaries/programs are simple to find and obtain. The primary listing should probably be operating system and/or web server, then hosting etc. I do not think there is any point listing by language here, unless they depend specifically on the language (ie, certbot and python version(s)).
Intermediate - Open source clients / plugins/extensions for existing programs.
Open source clients that can be tinkered with, compiled and run, eg: uacme. Could also duplicate any clients from the above and list by language. This could also include plugins that extend existing programs with acme functionality. Another example could be DNS plugins for certbot.
Advanced - Libraries
Pure libraries, or also programs that fit into the above categories that can also function as libraries, eg, lego.
Projects integrating with Let's Encrypt
Caddy, etc.
To be honest, the last three dot points could be their own page. However, I put forward that the beginner/just want a certificate page should be emphasised, or listed, first - as my guess is that is what the majority of people need to know to start with.
I agree with your point on background and context, and I believe this could better organise all the options while still encouraging people to explore said options. At the very least, provides a slightly easier onboarding path. With more focused pages these could be expanded, like you say, with more information / a summary for the options and be slightly less intimidating than a giant list of hyperlinks without a heap of context to each link.
Completely agreed. I have found it kind of odd that when people ask here about how to get started, we can point them to that giant page of clients, and maybe make a couple suggestions ourselves if they've said something specific that they're looking for and we have some experience with that scenario, but that's about it.
The only reason to group by language I think, is that if I've been having trouble installing certbot and whatever dns plugin I need (or have trouble with it being on the same system as some other python program since their dependencies conflict), I may be looking for something that's specifically not python. I don't know if other platforms/languages have that problem for other people, but I know I personally have found it to be a real pain when trying to get anything python-based working.
Grouping by installation method (snap, package manager, Microsoft Installer msi, etc.) may be closer to what people need on that axis, though. And certainly a more comprehensive "filter by feature" would be even more useful.
Not sure if this should go into the general help guide or both there and in the client list.
At the very beginning, a description of what a client is would probably be very helpful to noobies. Quite often I've seen users being told they have to choose a client and their reaction is "Huh? What's a client?" Some really have no clue about the terminology. The description doesn't have to be elaborate, but something general. Some users have come to a screeching halt when they're told to choose a client... and finally ask, "which one do I use?"