Request:
This is an open question to Certbot community maintainers, forum sages, etc. who might have thoughts or input. We are looking into possibly adding tutorials or explainers to Certbot documentation. We wanted to survey the community for ideas or topics that could be potentially documented better.
Some questions to ponder:
Are there common issues or problems you find yourself explaining in the Certbot community that could be assisted with better documentation?
Are there any external tutorials or resources you often link to, as an explainer for Certbot functionality or setups?
Any existing documentation we have that could be amended to explain a basic Certbot concept better?
I think a lot of people are just confused about what the client checks versus what the CA checks, and overall how the WebPKI works. I'm not sure how much certbot documentation can help with that, but it's helpful to keep in mind when doing any sort of documentation that a lot of people don't yet have the basics, they just want their site to work. (More often than you might think, people know they need a certificate but don't know they need to even register a domain name.)
I like a lot about the certbot home page, trying to describe the prerequisites of having a working site already, and that one's hosting provider may already include a way of securing sites without needing certbot. But if they don't have a working site already, people aren't sure what to do. I think this is exacerbated by .app and similar TLDs that are in the list that browsers won't connect over http on, since people can't see whether their site is working over http using their normal browser.
The main complaint I would have about the certbot documentation is why in the world when I click my platform is "Windows" on the certbot page, does it still tries to give instructions to install it? Like, there's a message at the top that "Certbot has discontinued support", but then it proceeds to try to give a bunch of instructions anyway, including links to Github for download that just 404. That's tripped up a lot of people and seems awfully confusing.
Just my first few thoughts; I'd love to hear from others as well.
It may be orthogonal to what you're asking, but I think one of the bigger messages that needs to be pushed at this point is to stop using standalone ACME clients like certbot, acme.sh, lego, etc., if possible. Let's Encrypt has been live for over ten years, and most of the popular server software now has ACME built-in (e.g., Caddy), or as an available module (e.g., mod_md for Apache). We should, IMO, be encouraging people to use use these capabilities if possible, reserving the use of such standalone clients for cases where the server software in use doesn't include this capability, or when its capability is inadequate (e.g., you need DNS validation, but the software can't handle it).
A couple more things, if "error messages" can be included in what you're thinking of for "documentation":
It's sometimes confusing that for any error, with any CA, the error message directs people to this community. I mean, I don't know if it's really a problem that we're the de-facto all-of-certbot support, and an ecosystem of many ACME-supporting CAs helps secure the Internet and fulfill ISRG's mission regardless of whether the CA is actually Let's Encrypt. But it's sometimes a little awkward when someone is using it with a commercial CA and then ask us for support and for an understanding of that CA's offerings.
Similarly, it can sometimes confuse people that --dry-run uses the Let's Encrypt staging server even if their regular certs are from a different CA. Again, I don't know as it's really a problem, and other CAs don't always have public staging systems. But like, it's not obvious that one would need to also have Let's Encrypt in one's CAA record in order for the dry run to succeed even when configured to use some other CA. So I think maybe there is room for documentation improvement there, somehow.
I may be presenting problems more than I am solutions, though.
An overview of how to use Certbot would be nice. There is a lot of good reference material but that is a lot for a newcomer to digest and make into a plan. An outline for this "how to"
Get your initial certificate using one of these commands
(examples for certonly, --apache, and --nginx)
When successful Certbot creates a renewal config file with those options
The Certbot renew command processes all these config files to renew your cert
Describe a cron/timer is usually setup during install and refer to existing topic for details
Maybe give tips on requesting a cert such as naming all the domains you will be connecting with (ex: www subdomain).
Include a section for --apache and --nginx to describe what they do (w/out certonly) to your web server config. Maybe give example of the minimum port 80 VHost/server block. Describe what, if any, changes might be made to your web server config during renew. (ex: updates to the options-ssl-apache file).
Perhaps give guidance on best fit for --apache and --nginx (w/out certonly). We have seen plenty of cases people using them for large or complex installs. When they start running into performance (or other) problems these are very difficult to debug. By the time such problems develop it is very difficult to rework their tooling for a better method.
This is definitely a big point of confusion. People will add a -d www.example.com even though they haven't set up a www in their DNS (or maybe in their web server config), since it just doesn't occur to people that from the Internet specs perspective those are completely separate names.
That's part of what makes it hard to know how to improve certbot documentation, since a lot of the education that's needed in order to use certbot effectively is really more general web infrastructure understanding documentation. Which people don't always want to become an expert on just to run their own web site.
Thank you everyone for the feedback you gave to this brainstorm. We took the main themes of this discussion and documented them to keep track of improvements and clarity we can provide as a team. Feel free to keep adding here while the discussion is open. But the respectful and thoughtful suggestions given so far are appreciated.
The fact that "run a custom script to satisfy challenges" and "display the token on the screen so that the user can manually place it somewhere" are both called "manual" is also pretty confusing. They're like, the exact opposite of each other.
Yes I do. 