Many modes of communication

I'd started talking about this a little in another thread, and then @tlrenkensebastian wanted more information on my perspective. I thought I wouldn't have time to write this all up, but apparently I wanted to procrastinate on other tasks more. So, here comes what I hope is some constructive criticism that might be a starting point for trying to make Let's Encrypt even better.

The core thing that made me start thinking of this over recent weeks is that sometimes I want to post a link to something "official" as a reply to a discussion here. And I'll know that I saw something once, and it must be around, but it sometimes takes a while to find it. And part of what makes it take a while to find is that there are several places to look:

  1. The documentation
  2. The blog
  3. The API Announcements category.
  4. Occasionally there are "official"-ish statements posted in other categories here too, sometimes just offhand as a reply to what somebody asked, but also as a separate post when it's important enough to mention but not deemed important enough to be an "announcement" (as in this recent case where new DDoS protection blocking was added), particularly if it's expected to be temporary and not affect many people.

So as some examples, if I want to answer somebody about why they can only get 90-day certificates that's in an old blog post, the plan for removing ACME v1 support is in API Announcements, and there's a list of upcoming and completed features in the documentation.

There was a little discussion of this in the recent discussion of rebooting the FAQ, that it might serve as a better "index" to the various resources in some way.

Switching to R3

For a more concrete example of a recent major change that I think could have gone better, I'll bring up the replacement of the intermediates at the end of last year. The official Integration Guide says that the way to get updates about important changes is to sign up for a forum account and subscribe to the API Announcements category. [Aside: This is the reason why I got a forum account, and ever since I've spent much more time on here than I ever thought I would.] But the actual announcement of the new intermediates was posted only on the blog Sept. 17, 2020. The post to the API Announcements category was on Nov. 24, 2020, and it said that the new intermediate might be issuing as soon as that day. (Though actual issuance didn't start until Dec. 1.) From being on the forums around that time, it sure seems that the new intermediate took quite a few people off-guard (even if they "should" been expecting it as the old intermediate was expiring), and I think for some of them the API Announcement was their first indication that something was changing.

Dealing with the expiration of DST Root X3

Now, the expiration of DST Root X3 is clearly a big deal integrators need to understand, and they've worked hard to get information out. The plan has changed many times, though, which I think has caused more confusion. There are many posts in API Announcements about switching to serving the ISRG Root by default, and moving out that date, and there were blog posts about what would happen too, and then the blog post got updated with a new plan of the expired-long-term-cross-sign, and while some of the blog posts and updates I think were posted to API Announcements I don't think all of them were. (For instance, this post mentioning the blog post was posted in Issuance Tech, but I can't find a link to that blog post from the API Announcements category though maybe I just missed it looking through just now.) More recently there is a new post in API Announcements with the latest status, but I think it's been a confusing road to get to this point, particularly for people who just get the emails from subscribing to API Announcements (like the Integration Guide tells them to) and don't otherwise keep up with the forum or blog.

So what do I think?

So now to answer the questions that prompted me to actually finally write all this up,

It's a mixed bag, I think. I do hate to complain, as I know it's a small staff and if I were supreme benevolent dictator of all things Let's Encrypt I don't know as I would do any better. Certainly the Integration Guide is pretty good and its main flaw is that not everybody who needs to know about it has read it. But it does imply that subscribing to the API Announcements category is all one needs to do in order to get updates, but I'm not sure that there's always a focus on ensuring that everything of note gets posted there. (And of course, if you post too much there then people get annoyed that they get messages too often, so it's a tough balance.)

This is a tricky one that I'm not really sure of. (Of course when you start thinking about your own "default" behavior you end up second-guessing yourself on everything.) I get notified on all the API Announcements, so I'm certainly aware of them when they happen. When I was trying to find info on the ACME v1 shutdown plan to post in some topic in recent days it took me more time to find than I expected, though, since I was looking in the documentation and blog but it was only in the API Announcements.

I don't know as I really care, as long as it was all in one spot, and I could get email notifications of it. (I don't see a way to get emailed new blog posts, for instance, but I'm more email-centric than other people probably are.) I think the API Announcements category actually works fine as a "place", but perhaps needs to be referenced more from the documentation somehow, and Let's Encrypt should be sure to also post there when a blog is posted that also impacts users? And other ways of getting the API Announcements for people who don't want to sign up for a forum account and get emails (RSS? Social media? I don't know what the cool people are using these days) should probably be prominently available as well.


Again, I'm hoping that this is constructive, and probably other people have better ideas for improving things here than I might. (I'm a software engineer, not a communications expert. :slight_smile: )

8 Likes

Hi! This is SUPER constructive and definitely something I have been thinking about a lot lately. Thank you so much for taking the time to put this into words, and thank you @tlrenkensebastian for bringing it up!

I actually have a social media post going out about a similar topic next week - to get feedback from a larger community than the forum as well.

For me, I always want people to go to the API announcements on the community forum. It's easier to chain so you can see the latest updates, as you mentioned technical things do change and our chain change has been one of them. It's been a lot, and I appreciate all of the feedback our community has given us about it.

I've also been working more directly getting into folks' email inboxes to push them toward the community forum. When we share information and when we know where to go for that information, everyone is better off!

But yes to all of this! I love getting constructive criticism, especially about comms. Thank you so so much!

6 Likes

Aw, shucks, t'waren't nuthin' @jple. All in a day's work, especially since the reason why I asked those questions is that they were prompted by another class assignment I had which I chose to do on LE (and on which I also got an A, thankee-very-much). I'm glad I helped get the ball rolling on gathering information about communications. I may not be a coder and I may not be a translator, but if this ends up being how I volunteer for LE, then I'm happy to do so.

1 Like

Thanks so much for writing this down, @petercooperjr. I didn't get back to you or this topic till now because I've been dealing with health issues and then I decided to skive off and play video games for a few weeks.

I totally understand how hard it is to interrogate your own behavior. But it can be useful. Like you said you're an email person and that's how where you'd look first for information. I'm also assuming that as long as it's consistent, you wouldn't have a preference for where things like API Announcements went, as long as you were able to customize how you saw them to include your individual notification preferences?

1 Like

Pretty much. Needing to sign up for yet another account (for this forum) in order to get notified of announcement that would affect my custom integration (or client I made, or whatever) can be kind of annoying, especially if all I want is to get them to appear in my email (or social media feed, or RSS feed, or whatever the cool kids use these days). Though if it weren't for needing to do that then I probably wouldn't be here, so maybe it's for the best? :slight_smile:

I think the key is to ensure that there's one place, and that from there it gets distributed to all the various popular notification platforms that people would want.

3 Likes

Hear! Hear! Peter! :beer:

It's nice to have one official (perhaps "canonical" is the right word) place to look for official announcements. It prevents second-guessing and confusion caused by distribution mistakes. For a great historical example of this, look no further than the number of flavors of the Bible that rival Ben and Jerry's.

2 Likes

Update:
We hear you. We love the API Announcements category. Keep pointing folks that way, I'll keep bolstering it internally and being sure to update our blog posts with new information in the API announcements category!! Just as an exercise from an outside perspective, has there ever been any technical information about Let's Encrypt that would not fit into that category? I can't think of any but maybe y'all can.

2 Likes

Client development (#client-dev), issuance policy (#issuance-policy), and issuance tech (#issuance-tech-questions) can differ with increasing shades of gray. Usually it's more industry-related/external technological issues/discussions that don't really fit API announcements (#api-announcements) too well. I struggle when recategorizing certain topics.

1 Like