Improving instructions for complete newbies

Feature Requests
31

Just to add yet another wrinkle (I guess I'm just bringing up more problems rather than solving them; sorry about that), sometimes the person trying to get help here doesn't even know what "Let's Encrypt" is and isn't trying to set up a server, but keeps seeing an error message on their phone, and by clicking around the only text they can find about what it is says "Let's Encrypt" so they find their way here. They often don't even recognize the hostname that it says there's a failure connecting to, and if it's something like in their phone's email settings it just "pops up" no matter what they're doing so they don't know what causes it. Sometimes the issue is that it's actually malware on their phone for which the certificate stopped working, so when they come here asking about it people here go about trying to help them fix the server when that's not actually what they need help with at all.

Some of this is perhaps UI on the phone could be a lot better, but until that happens we might need some way to determine whether somebody here is even trying to set up a server or not.

For some example threads where people weren't trying to set up a server but were just confused by their phone's messaging (sometimes leading to confusion on the part of those trying to help as well): Let's Encrypt got on my iphone without permission, Help Pop Up Message, Newbie trying to understand.

6 Likes
32

Naw. In community development parlance, I'm listening to you as a member of the community tell me the issues you've noticed in the past when it comes to new people asking for help. Bringing up those issues is a part of that. If you didn't bring it up, how could we work together to mitigate it? I mean, I could probably infer such things from reading all the threads myself, but your pointing it out reinforces the validity of it being a real issue.

(Gonna come back to this thread in a while; I've got homework to do.)

5 Likes
34

I thought I was the conspiracy theorist here! - LOL
Yes, yes; definitely a hidden message there in the choosing of that name...

3 Likes
35

Oh yeah, this reminds me of how Apache and other servers have had so much trouble with people contacting them about misconfigured sites:

4 Likes
36

I hear you there, @schoen.

As @rg305 is fond of saying:

Got a problem? Just add certbot!

There are a great many people who come here who seem to be operating under the assumption that the involvement of Let's Encrypt certificates in their world somewhere means that we're the ones to ask for help. Often, of course, we do try to help them. There comes a point though when their requirements/demands are no longer reasonable. There are usually one or two members each month with "goalless projects". The regulars/leaders in this thread know exactly who I'm talking about. :grin:

3 Likes
37

@tlrenkensebastian, I made a very rough draft based on the three situations I mentioned above. (Some parts are a little duplicative with some of the EFF Certbot documentation, which also has a glossary and a lot of glossary links, whereas this draft generally doesn't define many terms or concepts.)

Let me know if you think there's anything potentially useful here, and, if so, we could keep working on this to improve its usefulness further.

Preparing Your Site for a Let's Encrypt Certificate

This document is meant to provide some more context and suggestions for people who are planning to get a Let's Encrypt certificate for the first time, but haven't started the process yet.

We're assuming that your goal in getting a certificate from Let's Encrypt is to use it to enable HTTPS on a public web site, without resulting in browser security errors. This is by far the most common way to use Let's Encrypt's services (although they can also be used to enable secure connections to some other kinds of Internet services).

To find the most relevant information, check which of these cases best describes your situation. If you need more help or clarification, you can also visit the Let's Encrypt Community Forum and ask about whatever you didn't understand.

Situation 1: I'm just beginning to create my web site; my web site isn't operational yet

In order to run a public web site, you typically need a domain name and a web hosting provider. The domain name is usually purchased from a domain registrar (although in some cases you might get a subdomain from someone else, like your employer when setting up a site as part of your job). The domain registrar and web host could either be the same company or different companies.

If you haven't picked out a web host yet, we suggest that you take a look at the lists of web hosts who support Let's Encrypt from EFF or on the Let's Encrypt Community Forum. (These lists are based on the same data, but they present it differently.) These lists collects web hosting companies that offer Let's Encrypt as an automatic, built-in part of their web hosting plans. If you use one of these plans, you should be able to get a certificate and HTTPS support automatically and not have to do anything else!

If you've already chosen a web host but it isn't one on the list above, ask your web host's support about the options for HTTPS with your hosting plan. Your web host's support team should understand the options well and be able to give you appropriate advice for your situation. If not, consider switching hosting providers!

If you intend to use a dedicated server or VPS plan (where you are the system administrator, responsible for installing and configuring all the software on the web server), you should go ahead and get your site up and running with HTTP, and then skip down to "Situation 2" below. This also applies in the case where you've chosen to host your website out of your own home from a personal server. (A dedicated server or VPS usually isn't the best choice unless you're experienced with server administration. If you're getting one in order to follow a tutorial in order to set up a particular kind of site or service, check if that tutorial already has information about how to get a Let's Encrypt certificate. If so, you're probably best off following that tutorial, or working with the tutorial authors to improve it so it's more appropriate for your situation.)

Situation 2: My web site is available (works in a browser) over HTTP, but not over HTTPS

Congratulations on getting your site up and running!

Your options for switching your existing site from HTTP to HTTPS with a certificate from Let's Encrypt depend a lot on how your site is hosted and how you administer it. That can include the software environment used to host your site, your web host's policies, and the degree of administrative access that you have to the web server. Here are some possibilities that might affect your next step:

  • Do you, maybe, already have HTTPS working? Try going to your web site in a browser with https:// instead of http:// and see if it works! You might be pleasantly surprised if it turns out you were using a web host or web server software that already took care of this for you without even telling you.

  • Are you using a control panel? (This is a web-based interface that lets you configure or administer your web site by navigating to a particular web address in a browser.) In this case, the best case is likely to be an existing option inside the control panel that lets you turn on HTTPS from there. If you can't find such an option in your settings, check the documentation for the control panel's software, or ask your web host's support where it is (or whether the web host has deliberately disabled it).

  • Do you (or can you) administer your web server? (This typically means having access to a root shell or administrator account, and may mean that you or your site are the primary or only user of that server machine, as contrasted with "shared hosting".)

The recommended way to obtain a Let's Encrypt certificate on a server where you are the administrator is by installing a Let's Encrypt client application. This is a software application that runs on your web server machine and requests certificates from Let's Encrypt for you. There are many different options available, suitable for different environments and experience levels.

Whichever way you decide to proceed, you should also be aware of the potential pitfall of "mixed content". Mixed content refers to the situation where a site accessed over HTTPS references resources (like images, scripts, or stylesheets) located at HTTP URLs. For example, if your site's HTML contains <img src="http://example.com/image.jpg">, this will create a mixed content issue once you activate HTTPS because of the hard-coded HTTP address. The typical symptom of mixed content is an error or warning message from a browser when accessing an HTTPS site with this problem, and possibly reduced site functionality or partly broken rendering of a site's content. Before or immediately after switching your site to HTTPS, try to check your pages' HTML to ensure that there aren't hard-coded HTTP URLs left there. If your site's code is generated by a template or CMS, you may be able to change a single setting (such as the "site" or "base" URL) to fix this problem everywhere in your code all at once.

Situation 3: My web site is available (works in a browser) over HTTPS; I have an existing certificate from a different certificate authority and am thinking of switching to Let's Encrypt

Let's Encrypt is a little different from most other certificate authorities. One difference is that Let's Encrypt certificates are always free of charge; Let's Encrypt doesn't charge you any fee for issuing them.

Another difference is that Let's Encrypt certificates are only issued using special software applications (called "Let's Encrypt clients" or "ACME clients"), which can automate all or some of the process. They're not issued by contacting (or providing documentation to) a human being working for the certificate authority, and they're not issued by completing forms on the certificate authority's own web site.

Another difference is that they last for only 90 days (not longer periods such as 12 months, which you might encounter with other certificate authorities). This is meant to promote automation, by integrating software with your web server to renew your certificate automatically before it expires, ideally without any intervention on your part. Like your original certificate, the replacement certificates will always be provided free-of-charge.

Check your web host's documentation, or ask your web host's support, to find out if your existing hosting environment already supports Let's Encrypt somehow, making it easy to switch over. For example, on some web hosts, you might be able to enable Let's Encrypt by setting an option in a web-based control panel.

Otherwise, the recommended way to proceed is installing an ACME client application on your web server. If you can't install new software directly on your web server, and you don't already have Let's Encrypt software support in your hosting environment, switching to Let's Encrypt may be inconvenient or difficult -- especially if that means that you don't have a way to make the relatively frequently-required renewals happen automatically. But in any case, if you decide to proceed, you can follow the suggestions in situation 2, above.

[...]

5 Likes
38

I'm in a class about the foundations of community-based research (CBR) and one of the founding principles is that if you're doing research in a community, you need to share with the community what the research is for and most importantly have the community give input into how to perform the research. And even more importantly, explicitly share the results and findings of the research. I hypothesize that a reason why "people generally hate surveys" is that they were not told what the survey was for, didn't have a hand in designing it, and weren't able to see how their participation made a difference in the results or conclusions made by the researcher.

CBR as a research methodology really took off in the 1990s (or so says my brief search of journal articles) so it really hasn't had a chance to disseminate into other academic disciplines or has been applied fruitfully in many arenas. I think that if I were to apply this type of methodology to the research question of "How can we make installing security certificates into websites more accessible to the average user?" I might actually be able to get some useful feedback.

5 Likes
39

Overall, this looks pretty good to start with and I think it's potentially very useful. A way to interrogate this text would be to go back through the Help forums to pick out the threads where there was a communication barrier and see if the explanation covers that use case in a way where linking to the section of the new doc would help explain what's going on. For example, the second response in this thread (Could not issue a Let's Encrypt SSL/TLS certificate - #2 by JuergenAuer) isn't covered under any of the situations and a solution would be to further define what a domain is under the first paragraph of Situation 1. Something simple like "www.example.com" is a domain and "your.example.com" is a subdomain.

How far back would you like for me to go?

5 Likes
40

Also, do we need to have this moved into Documentation now?

2 Likes
41

Do you have any insights as to why they're a source of confusion?

Hence my suggestion of amending the Help template to have a part where either at the top or the bottom of the forum the person asking for help can state how much experience they have in installing a cert. I think it needs to be an open-ended statement provided freely by the questioner so that they can gauge for themselves how much help they want. That might also prevent the "information overload/underload" communication barrier I mentioned earlier upstream.

In the specific context you're quoting, I was referring to overall intelligence. In a computer-mediated communication context, I'm referring to the fact that even if someone is a newbie in one specific way they may know a lot about or have tons of experience in another topic which the person answering the tech support question does not.

3 Likes
42

This is actual two distinct parts:

  1. Someone obtaining and installing a LE cert on their own; and
  2. Hosting providers obtaining/installing a LE cert for their customers.

The first part is what this forum is all about. The second part depends upon what the hosting company wants:

  1. to sell their customers certs; or
  2. provide LE certs (which can be done two ways)
    a) provided automatically by the hoster; or
    b) provide the customer with an easy way to obtain/install a LE cert.

There is a list of hosting providers here on LE that have made themselves known that they provide LE certs for their customers (see Schoen's links above):

  1. automatically (and without any charge);
  2. will guide a customer through the process (free help); or
  3. will obtain/install the cert for the customer if they either do not wish to do it themselves or are unable to do it themselves.

The "tech support speak" does happen once in a while. :slightly_smiling_face: Once in a while someone will give the necessary advice to a "noobie" who is totally clueless as to terms and/or names of software clients, tech terms, and/or processes. For someone is even vaguely familiar with such speak, they have their solution at hand. However, for someone totally clueless as to what such terms are/mean, they are no closer to their solution - well, maybe a little bit - and need to be led through step-by-step... led by the hand if you will.

And once in a while you get those who demand help and want to know why everything isn't just a click or two and everything happens "like magic" for them.

This has been said on many help forums and blogs before (in several similar ways), "No matter how much time you spend on making a great guide, most people will never read it."
You couldn't begin to guess how many people have asked for help here and came right out and said giving their domain name wasn't necessary. After an exchange of 25 to 40 posts, they finally gave their domain name and the next post was the solution they were looking for, but made it so hard to give.

As for changing the documentation/guides here, I'm sure several people will have to look over any changes and agree to the way it is worded (changes, omissions, additions) before it would be amended to or replacing existing work.

Even the help template has to be carefully balanced between what information is required or helpful to provide assistance and to keep it short. The longer the template, the more of an inconvenience it would be to some while the more intimidating to others.

Edit: I'm long-winded. Just ask @rg305 and @griffin. :slightly_smiling_face:

3 Likes
43

I don't need to guess. I spent the last 1.5 weeks reading tech support forums, including this one! :smiley:

5 Likes
45

I thought your name was Jonathan? :wink:

That's an example of communication barrier #4, where there's a negative attitude towards the receiver. There's a little bit of #3 as well, where a receiver is feeling threatened. I don't want you to feel threatened by what I'm suggesting. I'm sorry if it made you feel that way; that was not my intent. On the other side of the dialectic, I'm a little disappointed that after quoting Jacob's post to me, you're assuming negative intent from me, especially after we both seemed to agree that assuming positive intent was a key element in speaking with people who are being critical of documentation.

I think that in a community like this one where its regular users are very invested in the project and are volunteering their time to help other people with the organization's mission they would be very interested in finding out what the results of the research are. Also, there are many different types of research methodology that do not require forms, such as interviews, photo-voice, etc.

I'm sorry, I should have been more clear. Do you have any insights as to why flow-charts in particular are a source of confusion?

I think that if given the opportunity, someone would not be intimidated by having to reveal how much experience they have in installing a security certificate. The way it's worded in the template would probably have to be done in a way that revealing that they don't know a lot wouldn't be considered an informational barrier to solving their problem using the existing documentation.

I think another way to consider the format of the Help form is that it's not only a tool to assist a user asking a question in the moment, but it's also a tool for future "problem-havers" in narrowing down the type of problem they're having. A common trend I found on tech support forums is that the people responding express exasperation that the person asking a question hasn't searched the forum (or Knowledge Base) first before beginning a Help topic.

However, if enough people in this community think that it really wouldn't be of help to amend the template even further, there are probably other methods available to alleviate the experiential mismatch communication barrier. Do you have any suggestions?

image
image911×168 23.2 KB

My specific question about how one would rewrite the initial instructions given by my webmaster has been solved. Schoen did that way back in his second reply to me.

Now, he and I are now further iterating on that message while you and I are discussing whether or not there actually needs to be additional documentation for users like me. The conversation is no longer about a Feature Request and the other categories don't apply either. Because part of ISRG's mission is to reduce educational barriers to a secure Internet, I think that goes in the category of "various aspects of...services" don't you?

3 Likes
47

In a world filled with every shade of every color...
The sense of

seems more like misstated inclusiveness than an actual significant "type" [representative of anything outside of your own limited 10 day view of those that didn't fit the category you seem to represent (those that were too overwhelmed to do anything more than just read a few posts - never getting involved and never even attempting the first step in certifying their sites)]. Instead of countless, I hear uncountable.
Mind you, I do think they exist, but so do the other countless other types that won't be lured/caught/helped by a targeted set of questions.
I too have tried to rectify the shortcomings of the single dimensional help questionnaire (one-size-fits-all approach).
My conclusion was that it simply couldn't be done (that way); and that a more dynamic questioning approach needed to be used.
I had even proposed that a wizard should be written, and used to gather the pertinent information. Using a simple checkbox type format, they would be presented with only one question at a time and the next question posed would depend heavily on the answer(s) to the previous one. But that was filed away with all the other good ideas that were just not doable (at that moment - like: "Time Travel" LOL).

Wow, sorry about the lengthy drabble - hard to see how much has been written in the little box provided.

6 Likes
48

I'm rubbing off. :stuck_out_tongue:

4 Likes
49

I'm sorry that you felt like you had to test me.

Not "make/demand". Request and suggest. Perhaps a little bit of pleading.

Well, no. As previously stated, one of the biggest roles of a community developer is to listen to people. You're definitely the person who has engaged with me the most on this thread and certainly the only person so far who has reacted in a defensive manner such that you're questioning my previously stated motives. (That seems more like an interpersonal issue, though.)

I'm really not sure what that means. Could you explain that a little bit more?

You could have also just asked me to elaborate more, rather than create an environment in which an outside person reading this thread could reasonably construe that you were being hostile.

I had a discussion with my webmaster about this thread. He also acknowledged that the initial instructions he sent were not as user-friendly as the ones that Schoen wrote. In our discussion, he also acknowledged that it made sense for an organization like LE to want to work first on ensuring that webhosts and other folks with more technical knowledge could install certs easily and that documentation would be written for that audience. He also helped me see that a small webhosting service like his where the site maintainer has more direct control over the back-end is becoming more and more rare these days and most people with the money to create a website are turning to "pre-fab" web dev like Weebly or Squarespace for their hosting and e-commerce needs. In that sense then, the "like me" use scenario is actually not as average as I originally thought.

At the same time, I still think that it's to LE's benefit to ensure that any type of user who is reading the FAQ could come away with the sense that yes, with a little bit of work on their end, they could do this themselves and/or they have enough information to convince their supervisors that they should be doing this.

Dang, that's such a nice metaphor. Well done.

I'm going to point this out once, and then deliberately ignore it in the rest of your response to me. I don't appreciate your condescension and I'd like for you to stop doing it.

I'm confused here. Are you attempting to provide an example of a situation that happens here on the forum a lot and which wouldn't necessarily fit the use scenario I theorized about?

I also do that because I know a lot of people who provide technical support and I don't want to be the kind of end user they complain about.

I find that an amusing hypothetical question because I deliberately decided to learn how to drive a manual transmission vehicle after I got my driver's license because when my dad had a manual transmission Toyota Corolla hatchback, my mom could never drive his car and always had to wait for him to wake up from his naps or whatnot before she could go grocery shopping or do other errands. I never wanted to be stranded like that, so I set out to learn how to do it. And now I even have dreams about driving manual transmission vehicles.

The crux of the matter for me is: You could find yourself in a situation where you need to know a thing, so might as well learn about it now so that you know what to do when it happens.

4 Likes
50

That was useful and a very thoughtful contribution to the conversation and my understanding of Griffin's defensiveness. Thank you for that.

5 Likes
53

I guess when left to judge something without being provided sufficient context... some will always get the wrong impression.

So let me rephrase (add to) my previous post.
[since it refuses to be edited]

Here is a prefect example of what is never found, neither in life nor, in this forum:

Why?

Because no one comes here to learn.
They come here to solve their immediate problem(s):
They just want (a) solution(s); Not a full blown class - with instructional videos and a seminar on best practices and the juicy inside info on all the intricacies of their specific scenarios/configurations.

3 Likes
54

I disagree @rg305 ... This is a great example:

I love(d) this thread. It shows someone coming here for help and is willing to listen and trust the "helper"... and the "helper" listens, and is intuitive and experienced enough to know what the OP needs even if they don't know what to ask.

Both parties are willing to stick it out on the line and be honest with their grasp of the situation and ACHIEVE A SOLUTION while learning in the process.

So I challenge:

Most really don't, but some really do!

7 Likes
55

I love those topics, @Rip. :smiley: They not only result in achieving the technical outcomes, but also tend to result in truly satisfied customers with a full understanding of where they are. I always feel a sense of humility, gratitude, and mutual cooperation there. :sparkling_heart: I also tend to run out of likes in those topics too. :slightly_frowning_face: Totally worth it. Just means I need to revisit later. :revolving_hearts:

I feel like topics with 75+ posts should come equipped with a fairy fountain. :fairy: :fountain:

I get where @rg305 comes from though. We've been involved in many topics where the help-seeker can barely be bothered to click a link to a tutorial that will solve their real issue instead of what they think their issue is.

4 Likes