Let’s Encrypt is about letting anybody use HTTPS to secure their website. Our home page implicitly promises that securing any website will now be an easy process, no longer even in Beta, and not the difficult series of steps that securing a site used to be. Most folks who run small websites know how to use parts of management tools like CPanel or Plesk. They don’t know how to use certificates and certificate tools. They may not have much knowledge of how Linux commands work, the directory structure of the Linux file system, or how Apache config file directives work. Since Let’s Encrypt is now claiming to be meeting its goal, right on its home page, we have to make Let’s Encrypt accessible to everyone now. This means improving the current documentation. CPanel will offer Let’s Encrypt soon, hopefully in a simple way. Until then (and even after then), instructions for using Let’s Encrypt on the LE website need to be short, easy to understand, and must just work. The documentation must be a lot better than it is at the moment. The letsencrypt.org Get Started page needs to explain clearly what our tool is, how to install it, and how to use it to get and install a new certificate, and even how to convert an existing website to HTTPS. The current home page has one and only one obvious link to provide this guidance: Get Started, which points to https://letsencrypt.org/getting-started/. This Getting Started page is totally confusing for the vast majority of people who run small servers. We can see this by reading this forum, which is filled with confused questions. It is totally confusing for me, and I’ve been a professional software engineer for 40 years and a web designer for several years. One of the confusing commands currently on this page is: certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.is -d m.thing.is What, exactly, does this command do? Which of the strings here are literals, and which are placeholders, meant to be substituted? Which of these strings are pathnames that already exist on all Linux systems? Which are pathnames of directories or files that the user is supposed to create? Why isn’t there a detailed and clear explanation? Why isn’t there a nicely formatted, step-by-step list of instructions that anyone can follow to secure their website? Why aren’t we fulfilling our promised strategy of making it easy to secure any website? Forget what you know about HTTPS, certificates, certificate authorities, and how Linux, Apache, Nginx, IIS, sockets, tools, etc., work. Let’s have a competition to write clear, simple explanations of our procedure with clear examples, both ordinary simple examples and some more complex examples. Just my opinion. No criticism of any person is intended, or of the project.

(I apologize for using my own format for quotations. Don’t understand how to quote here.) cyrano: “I can’t even work out how to quote.” Your honesty is refreshing. I tried to figure out quoting and failed too. “I have letsenencrypt installed in the root of the disk, and certbot is installed in /home. Maybe that’s a mistake?” I’m not sure; I think that you are supposed to choose any directory and then keep Certbot in that directory, but I’m not sure of that. I think each one of your questions and issues is valid. cyrano: “All the confusion stems from docs written by developers.” I agree. Developers don’t get the training they should these days. In my projects, I grow good documentation as I design, implement, and debug. By the time of advance releases, I don’t usually have to do any further work to give my users complete instructions (whether they need completeness or not). They don’t seem to teach this anywhere anymore, judging from the LE project. Each of the companies I worked for in the 38 years before I retired (Digital Equipment Corporation, Prime Computer, Honeywell Computer/Multics, and about a dozen more) would have fired me for producing software that only had documentation that experts in the technology could understand. Note that some of the experts here have given you answers to your specific questions. They are happy to do that and do a very good job (they are incredibly patient and knowledgeable), but they simply cannot see that these questions reflect an underlying problem with the LE documentation (as opposed to Certbot, which has somewhat better documentation starting at its home page). That is why they have stopped replying to the topic of this thread, which is my claim that the LE documentation needs improvement. They evidently think that their ability to answer any question about LE or its installation is sufficient as public documentation. That is the way many developers think these days, IMO. They seem to have no ability to put themselves in the shoes of a newcomer to this technology. cyrano: “…the uninitiated get confused because they simply don’t understand the lingo.” There needs to be a sort of combined glossary and FAQ that could orient newcomers. cyrano: “…the ‘client’ should be named ‘certificate manager’, or something like that.” Yes, great idea. Back in the 1980’s I was confused when people started using the term “email client”. I finally got a straight answer, that it means “email program” (in more modern language, “email app”). Why can’t Certbot be called a “an automated certificate app”? Words like “client” are overused by the terminally smart, who are never confused by them. rugk: “I think that’s called FAQ and it is there: https://letsencrypt.org/docs/faq/” Have you looked at it? It covers only the basics, and not all of those. Lots of frequent questions in this forum haven’t made it into the official FAQ. Notices of updates and help information don’t belong just on websites. They belong in the apps as well (excuse me, the clients). rugk: “Mark the text you want to quote , a quote button will appear, click it.” smacks self in forehead Wow, so intuitive, yet I never tried that. Wait. I have tried it, and I just tried it again: I selected some text but no quote button pops up anywhere. What did I do wrong? Does “marking text” mean something different from “selecting text”? Does this forum not work on Firefox 47.0? rugk: “This is the ‘simple text’ you requested (also called ‘explanation’).” Disagree. Text stuck in a blog for a particular date is not simple text, since it is not obvious to anyone except someone who would take the time to read the entire website. This is not a reasonable requirement for newcomers. rugk: “But users only use the client and should not care about the server.” I think this is exactly the point; why use the word client and confuse newcomers? rugk: " ‘certificate manager’ is not a real anme and it sounds lame," Then call it ACM (Automated Certificate Manager). That sounds spiffy. Anything but ‘client’, which is a technical name relating to the fact that LE happens to define a client API called ACME. I agree that ‘Certbot’ sounds great, and, except for history, I wouldn’t object if LE changed their name to Certbot (with EFF’s permission). rugk: “That’s a good point, but it’s a bit tricky to do this [provide a man page up front]” Nonsense. Just include a pointer to the man pages on the homepages of LE and Certbot. Nothing could be easier. rugk: “First of all, we have language that can only be understood by someone familiar with Let’s Encrypt/ACME. Getting rid of that language or adding simpler explanations absolutely makes sense, Let’s Encrypt should not expect users to know these things.” Bravo! Let’s improve the documentation before people have to report specific problems.

[image] david7364: (I apologize for using my own format for quotations. Don't understand how to quote here.) See my earlier post: [image] rugk: here is how to do it: Mark the text you want to quote , a quote button will appear, click it. Edit: Noticed, you saw it. See below. [image] david7364: Lots of frequent questions in this forum haven't made it into the official FAQ. You can just add them. The website is now open source too: [image] GitHub - letsencrypt/website: Let's Encrypt Website and Documentation Let's Encrypt Website and Documentation. Contribute to letsencrypt/website development by creating an account on GitHub. [image] david7364: I selected some text but no quote button pops up anywhere. What did I do wrong? Do you have JavaScript disabled? [image] david7364: I think this is exactly the point; why use the word client and confuse newcomers? Good point. I just checked https://certbot.eff.org and searched for "client". The word is not mentioned at all... However on the LE site it is mentioned. [image] david7364: rugk: "That's a good point, but it's a bit tricky to do this [provide a man page up front]" That's not my quote... :expressionless: [image] david7364: Then call it ACM (Automated Certificate Manager). This would lead to confusions between ACME and ACM. I think you wanted to make it easier not harder? :wink: [image] david7364: I wouldn't object if LE changed their name to Certbot (with EFF's permission). No, just because you have to differentiate: Certbot is the client software you use and Let's Encrypt is the server service you use. [image] david7364: rugk: "First of all, we have language that can only be understood by someone familiar with Let's Encrypt/ACME. Getting rid of that language or adding simpler explanations absolutely makes sense, Let's Encrypt should not expect users to know these things." Also not my quote... That's why you should use the real quote feature. You may ask why it does not work in the official Discourse forum: https://meta.discourse.org/

[image] cyrano: Maybe there simply should be a separate docs team, with people who are good at explaining and who can serve as an interface between devs and the outside world? That is a very good point. Seriously. I mean it. But unfortunately there is a small problem (that potentially could be solved somehow). Any company at which we pay for our certificates would listen to the paying clients and go out to hire a good technical writer. The newly hired resource would have to learn the innings and the outings of how the 'client' software interacts with the service provided by the LE server run by the LE team. This newly hired resource would then have as a task to write down, and constantly maintain, this information in a language 'anyone' could understand. That's a huge task, though many companies do this, with more or less success. The company will have to pay a salary to the tech writer. Taxes. Social security. Deal with sick leaves. Vacation. Ordinary stuff like that. It doesn't come for free. It's expensive. No problem. the company gains profit from the sales of certificates. Let's Encrypt is run by enthusiasts, on their free time. If anyone of the LE people get any kind of economical reward for their time and efforts, I'd be surprised, because I fail to see where the required revenue would be generated. So, "things must be better" is probably a true statement in most software projects, including LE. How to make it happen? Well, someone must step up and say something like: "I'd be happy to spend hundreds of hours learning the details of how this thing work. I'm also very skilled in writing very user-friendly documentation, including pictures and use cases. I'll be happy to help. Where do I sign up?" Now, when that is all said, it's quite common to see people studying the shoes they wear. Or the more straight people saying things like: "But I'm busy. I've got a daytime work. And a family. It's summer and vacation-time. I'm sure you understand that I can't find the time to do all that." Well, all those time constraints are valid for open source developers too. Still, they sometimes ignore their families, their vacation and sometimes even their day-time work to give you access to free (as in beer) TLS certificates that you can use on the Web server computer that you do administrate. I'm also aware that things "could be better". I agree with you on a number of points, though not all. But the right approach would be to humbly point out what is unclear (in detail, with references, making the life as easy as possible for the developer team) and humbly ask if it could be approved upon. From there, proposing your time to help... Well...

Biker, I like your writing, and I thank you for your time. But I see a flaw in what you say, a basic one. Your thesis cannot be true, because so many open source projects have wonderful documentation. I mention a short list near the beginning of this thread. While it does seem to be true that the developers on LE don’t seem inclined to put effort into good documentation, just into solving problems, I don’t think that has to be true. All it takes is the ability to put yourself in someone else’s shoes, to imagine how LE should be described if you are a newcomer to it. The only thing that could interfere could be a sort of “let’s do this the way we’ve been doing it” mentality. And such an “obstinacy obstacle” is easy to drop, if you want to. Documentation should be written by the experts, not by clumsy newcomers like me. I’m willing to write, but I’m the wrong person because I don’t know what to write. The people who know refuse to do it!

But a “clumsy newcomer” could learn. “The people who know” might just not have enough of their time to do that, too. Or might not have the right skill-set to write high quality end-user documentation. Someone will somehow have to step up. It will most likely happen. Most open source projects I’ve seen have started out in a very simple way, but (sometimes frustrated) people have taken their time to learn and then to contribute.

Biker, I hope you are right and that it will happen soon. I worry that some respected reviewer will try to convert their insecure website to secure using LE and report to the world how difficult they found the process, or even that they finally had to give up. Yes, some newcomers probably have good experiences, but we haven’t even tried to test the usability of LE. We have no idea what an impartial reviewer, not intimately familiar with SSL, would find. And it seems we don’t really care. We’re too busy. Too busy to avoid the bad reviews that might be just around the corner?

[image] david7364: cyrano: "I can't even work out how to quote." Your honesty is refreshing. I tried to figure out quoting and failed too. Thanks, David, I was looking for the button in the wrong place. If you scroll down fast enough, it doesn't appear :smiley:

[image] Biker: That is a very good point. Seriously. I mean it. But unfortunately there is a small problem I know. But I am supposing this is an EFF project and as such, sometimes things are simply necessary. I don't want to meddle in someone else's purse, though. Maybe they could look at the way FreeBSD handles docs: The One And Only HandBook A forum for specifics about the many configs out there Info for devs on their preferred planet, github I think. The second and third items are already in place and functioning. And when it comes to suggestions, I'll keep notes and report back. Do I open a new thread for these suggestions, or do we keep everything in here?

cyrano, It doesn’t work for me here. I am currently being helped by someone at the “Discourse Meta” forum. Quotation works for me there, but not here. Added 7/8/16: They finally figured it out. There is a Discourse preference for that specific feature. I checked it, and it now works.

Cyrano, I’m not an expert, but I think your idea is a good one. I wouldn’t do it in this thread, which is already ‘loaded down’. And I would recommend that you find someone central to the LE project to work with, so your efforts won’t risk being lost or ignored. Just my opinion; make your own decisions.

Let's make Let's Encrypt easy and simple

Help

Topic		Replies	Views
Easiest way to use Let's Encrypt Help	63	18240	February 16, 2016
Getting Bad Vibes Uncategorized	80	23148	November 26, 2016
Why is the "let's get started page" so vague Help	3	197	February 3, 2026
Improving instructions for complete newbies Feature Requests	61	6781	March 18, 2021
Simple and Clear Directions Feature Requests	31	16936	November 15, 2016

Let's make Let's Encrypt easy and simple

Related topics