Let's make Let's Encrypt easy and simple

[Biker]

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

[david7364]

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!

[Biker]

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.

[david7364]

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?

[cyrano]

@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

[cyrano]

@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?

[david7364]

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.

[david7364]

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.

[jsha]

@Biker

Let's Encrypt is run by enthusiasts, on their free time.

To clarify: Let's Encrypt is run by the non-profit ISRG, which has a small staff of paid employees. Certbot is maintained by the non-profit EFF, again with a small staff of paid employees. Both have limited resources, but do have a core of full-time staff.

We multiply the effect of those few staff with lots of help from volunteers, including the many people on this forum posting excellent answers (thanks)! We've also been talking with technical writers who want to volunteer on to work on our documentation, which I agree is a very important area of improvement.

Seth and Noah are already doing some nice documentation cleanup at seth and noah updated some confusing things [revisions requested] by SwartzCr · Pull Request #3232 · certbot/certbot · GitHub. I also saw some useful feedback on this thread that the word "client" is jargony and should be removed from the documents on Let's Encrypt's page. I'll aim at changing the language there.

I think one of the other broad themes here is that many people look for "how to's" via Google, and many of the ones that turn up are out of date with the rename of letsencrypt to certbot. I have occasionally contacted authors of documents like that to let them know. @david7364 and @cyrano, if there are specific documents that you see that are out of date, that might be one avenue to improvement. Similarly, if there is a third-party how-to with information you think should be incorporated into the official Certbot or Let's Encrypt documents, please do point it out and we'll see what we can do about incorporating them.

[david7364]

jsha, I am certain that you (and everyone else central to the project) are sincere. And I hope that your mention of volunteer technical writers will happen (note that technical writers must confer with technical experts before they can write).

But all of your proposed documentation fixes are rather minor ones. Removing the word “client”, the other changes that have been done recently, fixing bad “how to’s” on the Web, and issues with renaming of part of the project from Let’s Encrypt to Certbot, all of these are minor as compared with the issues that have been raised in this thread. I’ve already provided many summaries of the changes that I feel are necessary above, and I tire of doing it yet again.

Everyone on this project seems to be under the impression that the documentation (and possibly other areas) only need minor tweaks. Yet there is no evidence for this belief. No usability studies, even informal ones, have been done as part of this project. No objective or external appraisal has been done. There is simply a soothing belief that all is well. Good luck with that when objective external reviewers report on LE.

[jsha]

@david7364

technical writers must confer with technical experts before they can write

Yes, naturally we've been doing this.

@david7364

No usability studies, even informal ones, have been done as part of this project.

We actually did do some usability testing in the pre-launch period, and plan to do it again.

[david7364]

jsha, Sounds good. I’m glad I was completely wrong, and everything is just fine. Any day now the stream of help requests at this forum will undoubtedly stop, as people trying to use LE realize that it’s all so simple.

[jsha]

@david7364

Any day now the stream of help requests at this forum will undoubtedly stop

I think that's unlikely - people will always need help with any piece of software, no matter how simple or well documented.

But I think, from your sarcasm, that you took my narrow corrections as denial of your whole larger criticism that documentation should be improved. That was not my intention. However, if you're interested in providing useful feedback, please do so without the rudeness.

[david7364]

jsha, I apologize for my rudeness. Yes, I was being sarcastic. Another more specific apology appears below.

As described in this thread, the LE documentation has fundamental flaws that still need to be fixed, while everyone who works hard on this project, who are precisely the people who could fix this problem, seem to have no time or interest to do so. If you read this thread, you will see how frustrated I have become, due to

1. Being attacked for raising the issue (the moderator deleted the worst of the attacks).
2. A consistent attitude of “tell us the specific and localized flaws in the doc and we will fix it.”
3. A consistent attitude of “the many ‘help me please!’ postings would happen no matter what.”
4. X indicates that we are quite successful already (an example of X is “we have issued many certficates”; which does not actually prove that automatic installation was successful in these many cases); no automatic surveys have been included either on the websis or in the software to find out success and failure rates, either of the products or of the doc.

[Added 10:39 AM ET]
An example of a software-deployed success/failure survey are the following questions:

"1. Click here if you attempted to obtain an LE certificate manually (and successfully): [ ]
2. Click here if you attempted to obtain an LE certificate automatically using an LE-related cert manager or client: [ ]
3. If (and only if) you checked box 2, answer also the four following questions:
3a. What was or were the name(s) of the certificate manager(s) that you used (such as “Certbot”): __________________
3b. Choose the box that best represents your overall average experience:
[Succeeded] [Eventually succeeded] [More or less succeeded] [Failed]
3c. Choose the box that best represents your overall experience in obtaining your certificate:
[Very Quick] [Took some time] [Took a great deal of time] [Failed]
3d. Choose the box that best represents your overall experience in obtaining your certificate:
[Required only a few mouse clicks] [It was very easy] [Required a little web searching] [I had to ask questions on a forum] [I gave up]

If you read the whole thread, you will see that I have been mostly repeating myself lately. This shouldn’t happen in a forum. It is happening because the same four reactions (listed above) keep occurring here, bolstered by opinions presented as fact. I have often written before that almost all that I write here is opinion, not fact. But others do not state their opinions as such, because (I am certain of this) they believe their opinions to be fact, without having the adequate kind of evidence one would expect for facts.

I apologize for any slight slips in civility; I am trying very hard to present only reasonable opinions in this thread.

[jsha]

Fair enough, and I appreciate your thoughtfulness. In short - I agree with you that the documentation needs an overhaul, and also that it’s not as good as it could be, generally due to a lack of time.

Thanks,
Jacob