Improving instructions for complete newbies

[tlrenkensebastian]

About two or three years ago, my webmaster sent me some instructions he'd written about how to change my website to use HTTPS and to also acquire a security certificate from Let's Encrypt. I never got around to it and I'd like to try again.

Here are the instructions he wrote out for me. Speaking as someone who taught themselves to write HTML and only flirted with Linux once, these instructions seem very arcane, even knowing that my webmaster knows my exact level of technical knowledge. I'm also looking at the documentation that's available and I'm not entirely certain that it matches the ISRG mission of reducing educational barriers to secure communications.

If you were to rewrite these instructions for clarity to a less tech-savvy user than who is normally installing an LE cert, how would you go about doing it?

---BEGIN INSTRCTIONS---

These steps are less intimidating than they sound! The only parts that are tricky for you, and that I can’t do, are working on your embeds in Step 1 and thoroughly testing your site in Step 4. Everything else, I can usually handle for you when you say “go."

Step 1: Take a look at how your site uses images, stylesheets, and other embedded content. If you have a page that links to an embed using an “absolute” URL like “http://example.com/images/image.jpg”, most browsers will not render that when the page is accessed over HTTPS. This is a safety feature to avoid “mixed” insecure content on a seemingly secure page. Links like that can be changed to “relative” URLs like “/images/image.jpg” or even “//example.com/images/image.jpg”. (You rarely see that last kind of link, but it does work.)

Step 2: Go ahead and ask me to get your certificate and enable HTTPS. You can then browse through your site, changing the URLs in your browser’s address bar to have the prefix “https://“, to see if things work properly. Some sites will automatically redirect you back to HTTP for every single page; if this happens, I can work with you to figure things out, or you can skip ahead to Step 3.

Step 3: Make your site redirect all HTTP traffic to HTTPS. Some Web applications (like WordPress) can be set up to do this automatically, but this is a manual process for others. If you’re not sure how to do it, just let me know and I’ll help make it happen.

Step 4: Now is when it’s most important (and easiest) to thoroughly test your site and find any embedded content that’s broken, or other problems.

Step 5: After all the bugs have been shaken out, start serving Strict-Transport-Security (HSTS) headers to tell your visitors’ browsers that HTTPS should /always/ be used for your site. Some Web applications can do this, but usually I will do it. Note: There is no going back. This is recommended because an attacker could intercept the visitor’s session with your site /before/ your site serves the redirect to HTTPS, silently remove that redirect, and make everything look like it’s fine despite intercepting the traffic. HSTS negates this attack except on a visitor’s very first visit to your site (ever, or after several months of not visiting).

Step 6: Add your site to the HSTS preload list ( https://hstspreload.org/ ): a list of domains that should always use HTTPS that’s built into most Web browsers. Now even the very first visit to your site is protected.

---END INSTRUCTIONS---

[schoen]

Hi @tlrenkensebastian,

Thanks for bringing up this topic!

A large part of the advice that the webmaster sent you is about avoiding mixed content problems

https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content

which is technically a different part of web development than just getting a certificate from Let's Encrypt (although it's fairly closely related). It's conceivable that you or many other people in this situation could skip steps 1, 4, 5, and 6, without running into any problems. If you did run into problems, you could also get help here or elsewhere on the web to try to deal with the problems.

But I understand that your webmaster is trying to be proactive in order to head off potential problems and pitfalls in advance.

A big challenge in trying to write documentation for using Let's Encrypt, or any aspect of running a web site, is that web hosting and web development are so varied in terms of software environments. If people are using WordPress, there may be one set of things that are relevant to them (but not everyone uses WordPress). If they're using cPanel, another (but not everyone uses cPanel). If they're using Bitnami, another (but not everyone uses Bitnami). If they're using GoDaddy's or OVH's packages, maybe yet another (but again, not everyone uses these).

When people have come to this forum looking for help, we give them a form to fill out that asks them a lot of questions about their particular setup and hosting environment, in order to try to figure what kind of documentation or advice would be relevant to them. Some people skip over all this and just say "why can't you just tell me how to get a certificate?" or something, and we have to try to explain that there are more than 100 different ways of integrating Let's Encrypt certificates into a site depending on how and where it's hosted and using which technologies!

Also, something that I think you're alluding to, the different people doing this have very different levels of prior experience and knowledge. Some of them have had a certificate for many years from some other (paid) certificate authority and just want to understand what is different between Let's Encrypt and other certificate authorities. Others have a detailed knowledge of web development and server administration, but need advice about which software and settings would be relevant to them. And others are unclear on some of the background concepts (like the difference between a domain registrar and a web host, or whether they're on a shared hosting plan or have their own servers).

So it's really tricky to figure out what information to highlight and what to assume about people who are encountering this for the first time!

As a newcomer who is interested in the quality and accessibility of the introductory documentation, you could give very helpful feedback about what you personally find useful or not, or how you'd like to see things changed. Two places that are meant as entry points for newcomers are the Let's Encrypt Getting Started page

Getting Started - Let's Encrypt - Free SSL/TLS Certificates

and the Certbot landing page

Certbot

(Note that Certbot definitely isn't relevant for everyone, but EFF, where I was working at the time, put a bunch of effort into trying to make this landing page potentially helpful for everyone, including helping people understand whether Certbot is right for them or not.)

If you have opinions or questions about either of these, I think they'd be very useful!

If you want to learn more as a practical matter for dealing with your own personal situation (maybe in parallel with giving feedback on documentation), it would be best to start a new topic under the Help category, in which case a form will appear (starting with "Please fill out the fields below") asking you questions about your setup to help forum users get some context for what else to ask or tell you about.

Feedback on the questions in that form is also welcome and helpful.

[schoen]

@tlrenkensebastian

If you were to rewrite these instructions for clarity to a less tech-savvy user than who is normally installing an LE cert, how would you go about doing it?

Also, to try to answer that specific question, I would try something like this:

---

(1) One thing that's important to check alongside the process of setting up HTTPS on your site is "mixed content" issues. These are places where a secure HTTPS web page asks to load something (like an image, for example) over a non-secure HTTP connection. Web browsers find this to be a security risk and may block these, which would make your page look and work wrong.

You can help address this by checking the HTML code for your site and seeing whether it references "http://" anything inside the HTML itself (like an image, script, or stylesheet). If it does, try to edit that to change it to "https://" instead. If it's something loaded from your own site rather than someone else's, you could even delete the "http://example.com/" part entirely and use a relative rather than absolute URL.)

(2) You can then ask me to switch your site over to HTTPS. Once I've done this, you can try looking at your site in a web browser with https://example.com/ instead of http://example.com/ to make sure everything still looks and works right!

(3) Make your site redirect all HTTP traffic to HTTPS. (That is, if someone goes to http://example.com/ with a browser, your site will automatically tell them to go to https://example.com/ so they end up loading the site securely.) Some Web applications (like WordPress) can be set up to do this automatically, but this is a manual process for others. If you’re not sure how to do it, just let me know and I’ll help make it happen.

(4) If you or any visitors to your site run into any problems afterward, let me know! You can also try using a web-based scanner tool to check out your secure site and point out any possible problems. I can also explain whether or not things that these tools warn about are really problems or not.

(5) If you want, I can also later turn on a feature where accessing your site over HTTP instead of HTTPS will be completely blocked by browsers. This is meant to prevent some advanced attacks that try to steal users' passwords when they log in to your site over public networks. This is a bigger commitment because it's harder to switch your site back from HTTPS to HTTP in the future if browsers have been told that you'll never do that! Let me know if you think you would be interested in this.

[schoen]

Last note!

This part

@tlrenkensebastian

Step 2: Go ahead and ask me to get your certificate and enable HTTPS.

is officially the part that this forum is mainly meant to help people with (!). When people are acting as their own webmasters or sysadmins, they often find this part very challenging, especially if they're new to it. In your case you have someone who's planning to do it for you.

This seems like a good reason not to open a new Help topic (like I previously suggested above) because people would probably ask you lots of details about your setup and then eventually say "oh, since you have someone else taking responsibility for this, you can just go ahead and ask the webmaster to go ahead and do this for you".

Even if we can't help you that way, I'm sure we'd be glad to hear your feedback about ways that the existing documentation could be clearer or more helpful.

[tlrenkensebastian]

@schoen

When people have come to this forum looking for help, we give them a form to fill out that asks them a lot of questions about their particular setup and hosting environment, in order to try to figure what kind of documentation or advice would be relevant to them.

Yep, I've seen the Help form. And if I were to fill it out, I'd be putting either N/A or "I don't know" a lot of the time in response to the prompts, which would neither help me or the person attempting to respond to my query. I'm in a master's level class in strategic communication for the public sector and one thing that we learned recently is that a barrier to effective communication is that sometimes there's a mismatch between the sender's experience level and the receiver's. Do you think that it might be worth it to add an additional section to the Help template where a person could define how much experience they have in installing certs? Where in the form would you put it?

@schoen

Also, to try to answer that specific question, I would try something like this:

OMG, that is instantly more human-readable! I think that as a follow-up to Step 1, I'd want to know the easiest way to do all those replacements using my particular content management system (in this case, WordPress).

@schoen

This seems like a good reason not to open a new Help topic (like I previously suggested above) because people would probably ask you lots of details about your setup and then eventually say "oh, since you have someone else taking responsibility for this, you can just go ahead and ask the webmaster to go ahead and do this for you".

Yep. When I first heard about Let's Encrypt, I was really excited to know that it was a free service and I wanted to tell all of my friends who had websites to do it. But when I got that set of instructions from my webmaster, I became instantly intimidated by the amount of preparation I had to do. I also lurked on and off of these forums without signing up for an account for a while and I became disillusioned by how some people who seemed to have the same kind of website I have (a WP installation on a domain they purchased themselves) weren't able to successfully continue the install process.

@schoen

Even if we can't help you that way, I'm sure we'd be glad to hear your feedback about ways that the existing documentation could be clearer or more helpful.

Funny you should say that. For the first assignment in my strategic communications class, we were to write a presentation on how to prevent or alleviate communications barriers in a specific setting. I chose to do mine on tech support forums. AND, I just found out that I got an 88%, which is Canadian for an A. Or is that an "Eh?"

[schoen]

@tlrenkensebastian

Yep, I've seen the Help form. And if I were to fill it out, I'd be putting either N/A or "I don't know" a lot of the time in response to the prompts, which would neither help me or the person attempting to respond to my query. I'm in a master's level class in strategic communication for the public sector and one thing that we learned recently is that a barrier to effective communication is that sometimes there's a mismatch between the sender's experience level and the receiver's.

Yeah, I think that's a frequent challenge on this forum (and for technology education and support in general).

Do you think that it might be worth it to add an additional section to the Help template where a person could define how much experience they have in installing certs? Where in the form would you put it?

That's an interesting question.

One thing I think would be useful to some extent would be if we could break out Help into things like

• Advice/Where should I start?
• Conceptual questions
• Debugging problems with things I tried

If we could do that, I would expect to have only a portion of the questions from the Help template presented for each case. In the first case, I would focus on "where is your site hosted, with what kind of hosting plan, and how do you administer or configure it?". Only in the third case would we need to have the "I ran this command" and "It produced this output" questions.

But I don't know how well that would work, because I'm not sure if many people would understand how to choose the right one of the three kinds of "help".

@tlrenkensebastian

OMG, that is instantly more human-readable!

Thanks!

I think that as a follow-up to Step 1, I'd want to know the easiest way to do all those replacements using my particular content management system (in this case, WordPress).

I don't know much about WordPress, but I've heard some people have good experiences with this plugin, which tries to adjust the site content for you to prevent mixed content errors.

Really Simple SSL

This is a possible alternative to doing it yourself (like with search-and-replace in a text editor or something).

@tlrenkensebastian

Yep. When I first heard about Let's Encrypt, I was really excited to know that it was a free service and I wanted to tell all of my friends who had websites to do it. But when I got that set of instructions from my webmaster, I became instantly intimidated by the amount of preparation I had to do. I also lurked on and off of these forums without signing up for an account for a while and I became disillusioned by how some people who seemed to have the same kind of website I have (a WP installation on a domain they purchased themselves) weren't able to successfully continue the install process.

Another challenge for this is the question of whose responsibility various things are, or who wants to take responsibility for them. One thing you could see if you spent the past few years on this forum is a huge effort to get hosting providers to automatically provide Let's Encrypt as a built-in part of hosting plans, so that users don't have to take any action or configure anything in order to use it. We've had certain tensions and trade-offs around that effort (e.g. a debate about the extent to which we should sometimes encourage people to switch web hosts or not), but it is clearly the main goal for most people here.

There are also some cases where people's setups are difficult for them to administer. An example, though not the only one, is people who got a VPS plan (basically giving them a dedicated server and making them the administrator, responsible for all software and network configuration) when they don't really have system administration experience. In that case if documentation (or people on the forum) suggest editing a certain file, or something, people may not know how to do that, but it's the standard/only way for them to make the necessary configuration changes to their servers!

So in some cases I'm sure some of us want to say something like "you should consider taking an online class to learn more about the technologies that you use to run your site" or "you should consider hiring someone to help run your site for you" or "you should consider using a different hosting plan that takes care of more of the details for you". But we also want to be helpful to try to solve people's existing problems in the context in which they find themselves—but ideally without having to explain a dozen other background concepts or skills that aren't officially part of Let's Encrypt itself.

We also sometimes want to send people to other forums that are more relevant to what they're trying to do or figure out (even, sometimes, if some people on this forum do know the answer). But I guess we have a challenge about explaining our vision of the proper scope of this forum compared to others.

When I was at EFF, I was curious about having a really big interactive flowchart or wizard that would try to collect all of the context about a user's situation in order to provide the most relevant explanation of Let's Encrypt integration options for each user. As I mentioned, there's no single way to do it that would approach being relevant to everyone; in some cases it might be "run this command", in some cases "click this button", and in some cases "follow this tutorial" (or even "pressure your web host to do it for you, because your web host is seemingly deliberately making it difficult for you to do it yourself"), with different details in each case.

The current Certbot landing page is a very scaled-down version of that, but it does include some useful help for deciding whether or not Certbot is relevant to each person (which I think has been helpful in practice, because there was a tendency in the past to assume that people were on the Certbot site because they knew what Certbot was and thought it was relevant to them).

@tlrenkensebastian

AND, I just found out that I got an 88%, which is Canadian for an A. Or is that an "Eh?"

Congratul-eh-tions!

[tlrenkensebastian]

@schoen

So in some cases I'm sure some of us want to say something like "you should consider taking an online class to learn more about the technologies that you use to run your site" or "you should consider hiring someone to help run your site for you" or "you should consider using a different hosting plan that takes care of more of the details for you". But we also want to be helpful to try to solve people's existing problems in the context in which they find themselves—but ideally without having to explain a dozen other background concepts or skills that aren't officially part of Let's Encrypt itself.

I can appreciate this being a challenge. It's a basic thing in community development to listen carefully and mindfully to the people you're serving because they know what they need more than you do. The way the Help template is currently structured doesn't have a spot for that. I'm wondering if maybe it could be structured where at the beginning, there's a freeform section where the person who's asking for help can put (in one sentence) what it is they want to know, before delving into the nitty-gritty of what their domain is, what commands they ran, etc. That's typically how a retail customer service interaction starts anyway. Someone walks up and says, "I am having a problem with [INSERT PROBLEM]." The person at the counter then does all the fact-finding by asking questions. In an asynchronous environment like a tech support forum, the fact-finding burden is put upon the person who's beginning the interaction and so it does make sense for them to provide as much information as necessary to start troubleshooting the issue.

I'm wondering if, in the case of this specific forum, so many of the people attempting to provide useful answers are skipping the listening and fact-finding part and going straight into diagnosis. I looked at a lot of tech support forums for my assignment and that seems to be the case in almost all of them that I've seen. It also doesn't help that the culture around Internet technology has historically been one where end users were conditioned to fear tech support and Help desk staff were conditioned to think that their knowledge made them better than the end users who are coming to them for help.

Your thoughts? And hopefully other people who might be reading this thread?

[petercooperjr]

I know the format of the Help template has been discussed around here at times, with some people trying to make it a lot shorter (to focus more on what you suggest of "What are you trying to do?" and since to some extent it may be easier for us to derive their configuration from Server headers and the like than it is for them to know their configuration themselves), and some people trying to have it ask some more questions (so you don't need to spend extra time trying to tease out all the details one at a time). There's probably not really any greatly obvious better answer or it'd have been implemented by now.

And there are a lot of cases where they can just give their domain name, someone can run a quick scan with an online tool, and send the user in the right direction. So maybe we just need to put more links to these tools around somewhere?

One recurring theme I've seen, which again I'm not sure of the right answer to but I think is part of the challenge of bringing in newcomers, is that I think that a lot of the documentation and guides and such for "adding Let's Encrypt" is assuming that one already has a web site that's all configured correctly already for serving HTTP, and that one is just trying to "add HTTPS to it". I think that it comes from that being the main theme of Let's Encrypt and Certbot back when they were first made. But nowadays, a lot of people see HTTPS as just part of creating a web site (which is wonderful of course, and kind of the point of Let's Encrypt was to get us to this point), so people are trying to run through tutorials when they don't have a domain name or IP or web server or whatever set up yet. Some TLDs being part of the HSTS preload list only exacerbates this, since some people can't even see their own web site (in a typical user web browser) until they have HTTPS already set up, which can be confusing when the most common method of authenticating is HTTP-01 so they need to have a server running in a configuration that end-users can't see (just on port 80) as part of bootstrapping things.

[tlrenkensebastian]

@petercooperjr

...since to some extent it may be easier for us to derive their configuration from Server headers and the like than it is for them to know their configuration themselves

I can appreciate that being a challenge and I also think the environment which created this situation is a problem in itself. In my specific example, it's as if my webmaster just plunked down a brick wall between me and the concept of securing my website and said, "Here ya go! Here's this list of things you need to do in order for me to start getting you that certificate! Enjoy!" And I know I have to scale that wall, but I don't have any climbing gear or know where to get the climbing gear. In a circumstance like that, how helpful is the webmaster being, really? And this further helps to bolster the stereotype of webmasters and tech support people being unhelpful, which I'm sure none of you here want to see continued.

@petercooperjr

...people are trying to run through tutorials when they don't have a domain name or IP or web server or whatever set up yet.

That's why I think a document similar to the instructions I posted and @schoen improved called "How do I prepare my website for obtaining a Let's Encrypt certificate?" could be useful. I'd put it between the "How Let's Encrypt Works" and the "FAQ" document in the Overview section of the Documentation site.

[griffin]

@tlrenkensebastian

I'm wondering if, in the case of this specific forum, so many of the people attempting to provide useful answers are skipping the listening and fact-finding part and going straight into diagnosis.

Some people do that. I could name fingers and point names.

Most of us try to educate, which takes a lot more effort.

It's often faster and more effective to initially diagnose and explain why than to try to teach someone why they're looking in the wrong place.

[Osiris]

Isn't fact-finding and listening part of the diagnostic process?

That said, numerous help-seekers make fact-finding and listening very, VERY difficult Depending on the moment, one might not have enough patience.

[tlrenkensebastian]

I know about the XY Problem and I did read "How to Ask Questions the Smart Way" as part of my research because it was linked to one of the tech support forums I studied for my assignment. I was instantly put off by how much it appeared to perpetuate the notion that the people who are responding to tech support solutions were smarter than the people asking questions. In fact, the very title is off-putting and not welcoming at all.

@griffin

A single set of instructions would need to be generalized into oblivion in order to be a coverall.

I agree that a single set of instructions would not be useful. I also lean more towards what Peter and Schoen are saying where a flow-chart or different types of documents could be useful.

@griffin

I have done my very best to foster a welcoming atmosphere inclusive of all backgrounds, walks of life, and technical experience levels.

I appreciate this and I'm sure the people you helped appreciated it, too.

@griffin

I've found that understanding the needs and desires of those coming here is a complex, nuanced, and personal process that cannot be nicely fit into a box.

Agreed. You'd probably need to perform a survey of those people who have asked questions and phrase the survey in a way that not only gathered quantitative data but also qualitative data. In fact, I wrote a project management plan for another class on how to improve communications specifically in this very forum. The LE staff person who worked with me on clarifying some administrative details for my assignment said that my proposal got some wheels turning in their head, so that's a good start.

[griffin]

Amen to that.

Many of them often move the goalposts ten times in a single topic (or just change the game entirely).

[tlrenkensebastian]

Well, that's a part of the customer service experience, too. "You don't know what you don't know" is a saying for a reason. And being able to point out what someone doesn't know in a way that's affirming rather than dismissive can be difficult as well.

@Osiris

That said, numerous help-seekers make fact-finding and listening very , VERY difficult Depending on the moment, one might not have enough patience.

But is that the fault of the questioner? Tech forums are computer-medicated conversations and in one of the papers I cited for my assignment, because anyone can read a tech forum message, the onus of understanding is on the person who is responding to the message, not the person beginning the conversation.

[griffin]

@tlrenkensebastian

a flow-chart or different types of documents could be useful.

To some. There are lots of flow-charts around here (and connected to here). I've found them to frequently be the greatest points of confusion.

@tlrenkensebastian

I appreciate this and I'm sure the people you helped appreciated it, too.

Thanks. I won't hold my breath for the other people. Gratitude is a treasure: both beautiful and rare.

@tlrenkensebastian

You'd probably need to perform a survey of those people who have asked questions and phrase the survey in a way that not only gathered quantitative data but also qualitative data.

There might be some ok with this. There will be many who will not. In my experience, people generally hate surveys.

[griffin]

@tlrenkensebastian

the onus of understanding is on the person who is responding to the message, not the person beginning the conversation

Without a reasonable understanding, how do you ask the right question? Hence why viruses actually work.

[griffin]

@tlrenkensebastian

I was instantly put off by how much it appeared to perpetuate the notion that the people who are responding to tech support solutions were smarter than the people asking questions.

How do you qualify or quantify "smarter" by the way? I've yet to hear an answer that doesn't set my hair on end.

[Osiris]

@tlrenkensebastian

But is that the fault of the questioner?

In my opinion, sometimes it is, sometimes it's not.

It's also a little bit personal or cultural. What makes so much sense to me (to educate myself into a subject before asking for help for example), might not be a natural thing to do for someone else.

[schoen]

@tlrenkensebastian

That's why I think a document similar to the instructions I posted and @schoen improved called "How do I prepare my website for obtaining a Let's Encrypt certificate?" could be useful. I'd put it between the "How Let's Encrypt Works" and the "FAQ" document in the Overview section of the Documentation site.

I like this idea and I imagine it could have three alternative sections:

(1) My website isn't operational yet

(2) My website is available (works in a browser) with HTTP, but not with HTTPS

(3) My website is available in HTTP and HTTPS, currently using a certificate from a different certificate authority

It could then include different background and advice for people in each of these three situations.

The second one is the case that Certbot and a considerable amount of Let's Encrypt documentation are currently optimized for.

[griffin]

Just as a heads up, @tlrenkensebastian, if you want a potentially interesting idea for a paper to publish, you might consider "lost in translation" in tech support. There are multitudes of interactions in this community where misinterpretation of the attitude of the help-giver has led to degradation of the experience and outcomes of the help-seeker.