Let's make Let's Encrypt easy and simple

(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.

1 Like