Totally understand.[1] I really like Discourse and I wrote this post because I want Discourse to have continued success.
Something I’ve learned is that communities don’t care for change, but they are much more open to change if they feel they have agency. There innumerable ways to give people agency. For instance, the tutorial could be turned into wiki posts so that people like me can update them. Implementing the ESR plan helps too because it gives people the option to not make changes right away.[2] Being able to write up my experience and have it seen by people who manage the open source project helps too. Especially since the stuff I complained about got fixed overnight. 
In “Listening to users considered harmful?”,[3] Kathy Sierra wrote:
Most of us realize that focus groups are notoriously ineffective for many things, but we still assume that listening to real feedback from real users is the best way to drive new products and services, as well as improve on what we have. But there’s a huge problem with that – people don’t necessarily know how to ask for something they’ve never conceived of! Most people make suggestions based entirely around incremental
improvements, looking at what exists and thinking about how it could be better. But that’s quite different from having a vision for something profoundly new.True innovation will rarely come from what users say directly.
As I said, I’m not a frontend developer. I don’t really understand why these changes were made or how they will benefit me.[4] And that’s ok if they will, eventually, make Discourse better.
Still, it can help people like me be onboard if I can see the vision a bit more clearly. For this change, the pitch is:
- a much better development experience
- will enable large performance improvements in future versions of Discourse
Sounds good, I guess? I didn’t particularly notice #1 and #2 could mean a lot of things. More effective for me would be something like (and I’m totally making this up):
- When we converted the official Discourse plugins we found that it shaved off X% lines of code. By putting the template in the same file as the JavaScript, the code is easier to understand and modify in the future.
- We set up a branch testing removing Handlebars completely and discovered that change made page loads X% faster. Not only that, we saw a potential optimization that could eliminate [some problem users have raised].
A little more detail with an eye to educating non-experts goes a long way toward maintaining trust. I might not like the changes, but how can I argue with fixing actual problems other users have faced?
OpenSSL has a similar dynamic. We have a Corporation (~15 people) that sells support contracts and a Foundation (10 people, including me) that looks after non-commercial interests. Our documentation lags too. While writing the original post, I noticed we still have references to features that were removed last month. I’m working on a PR for that. And we made some changes that downstream projects have been highly critical of. ↩︎
Less helpful for plugin authors who want to support communities that want to stay on the bleeding edge. But it’ll be great for me since I believe I’m the only person using my plugin. ↩︎
Her blog is gone from the internet, but there is a PDF archive. ↩︎
Not that I really matter that much in the grand scheme of things. I’m talking about me as a stand-in for other people who depend on Discourse. I do know me better than most, afterall! ↩︎