Improving instructions for complete newbies

I will push back a little bit here and point out that the majority of the people trying to help here on the forum are volunteers, who would like to have their time and expertise respected.

I don't mean that that gives them license to be rude, unconstructive, or dismissive, but it is a good reason for them to want questioners to try their best to understand their problems, be forthcoming with relevant information, and be receptive to suggestions and inquiries.

9 Likes

@schoen

I have had theories about this and the correlation to titles. Some here adamantly oppose wearing a title (often to prevent being seen as "superior"). I've found that many help-seekers tend to be far more receptive if they understand your experience and commitment. Ideally it would be nice if knowledge and experience could be recognized for their own existence. How do we know if someone knows anything? Seems a trust issue.

3 Likes

Hear hear.

As I see it, we have to work at an issue together. However, sometimes there are help-seekers who want to make their problem yours. Well, that's just not how this works. Just throw it out there and sit back and do nothing. I want to help you with your problem, but it ain't mine!

6 Likes

I agree, @Osiris. It's a fine line sympathizing while not empathizing. You want to dig in to help, but at the end of the day it's not your baby.

4 Likes

Yep! There are a lot of papers on communication barriers, and in the brief amount of research I was able to do, I identified 8 of them which I think relate to technical support forums:

  1. Information Underload / Information Overload
  2. Failure to adjust to the receiver’s language and experience level / Experiential Mismatch
  3. Where the receiver feels threatened / Threat Perception
  4. Where there is a negative attitude towards the receiver / End User Abuse
  5. Where the receiver doesn’t understand terminology / Terminology Gap
  6. Impressing instead of expressing
  7. Failing to close the feedback loop
  8. Failure to listen and/or read

From a community development background, one of the solutions is to work with the members of the community to design a communications standard which works for everyone. Hence, my reasoning behind finally getting an account and posting about this topic. I really, really want to make it easier for people like me to either install an LE cert on our own or find a way to make it easier for our hosting providers to do so. And I also really, really want more people to be less afraid to enter into a tech support forum and ask for help. In previous jobs I've had, I know what it's like to translate from "tech support speak" to "end user speak" and back. It's nice to be a part of that communications bridge, and yet I wish I didn't have to do it all the time.

5 Likes

Without a doubt, for sure! In a nonprofit environment, having people who are knowledgeable and can help without impacting the core LE staff is vitally important. Everyone who has ever set their fingers to code an ACME client that can handle a unique situation deserves a gigantic fruit basket-full of praise. It's heavy labor which they're doing to help other people for free and certainly there needs to be a lot of respect for that.

I think, though, you hit it on the head when you said earlier (and I'm paraphrasing) that while the overall mission of LE (and ISRG by extension) is to "encrypt all the things!", how to get to that goal has changed. The org has made huge strides in how they were able to finally get some form of support from hosting providers like Go Daddy whereas in the early days they couldn't even get them to give LE the time of day. It feels to me as if a long-term outcome has been reached before a short or intermediate-term outcome has even been addressed.

I'm not sure how you came to that conclusion. You linked to Jacob's post which implies that you already agree with a communication standard where people should come up with the kindest response possible to someone who appears to be criticizing unfairly the documentation standards here. How can that be considered "controlling a person's speech and style"?

3 Likes

Hence why I coded CertSage and @Osiris enhanced it. :grin: Doesn't get much easier than copying one file to your webserver, entering an email address, and pushing a single button. Certainly took some pains to get there.

Whenever I hear the word "standard", the word "governance" is usually not far behind. There's an enormous difference between encouraging kindness in the face of adversity and mandating compliance. Telling a remorseless child to apologize is meaningless tyranny. Subjugation is not education.

5 Likes

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

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

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

3 Likes

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

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

@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

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

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

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

2 Likes

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

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

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

5 Likes

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?

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