I've also seen the negative sentiment to the v2 docs. I've been hesitant to jump in on the community site because I've seen a lot of - very polite, like yours - RTFM responses, citing the work you've put in etc.
I am probably one of those people who would have flamed someone 20 years ago for posting a critique like this without _any_ time to help directly, but I'm not too proud to give you a "moron in a hurry" perspective, because I think it answers your question.
Firstly - maybe do nothing. This is just what losing your old users looks like. They make a lot of noise that things aren't the same, that they're lost, confused etc. and want you to sink a lot of effort into making them comfortable. It's probably not worth it! You know what your success metrics for Caddy look like - so if v2 is succeeding in terms of adoption etc. - just let users go, or trust that they will work it out eventually.
But as one of these muddled users from 5 years ago who has put v2 into production despite the confusion: the v1 docs were brilliant. They were written hand-in-hand with a piece of software that had a target user in mind, and was so clearly hungry for adoption. The Caddyfile remains excellent, an ambitious design to map out what admins truly wanted to configure in a web server, removing everything else.
I think that explains negative sentiment to the v2 docs - Caddy is not built around the Caddyfile any more. So the docs don't centre it, and so caddy doesn't look like it's designed to do the same things. With v1, I felt that as I understood the Caddyfile, I understood caddy, an important and magical new binary on my system. That was almost certainly a flattering lie, but it never faltered. Every experience I had with v1 backed it up.
The v2 docs make clear that the Caddyfile is _legacy_, and that my old understanding doesn't help. The "Getting started" guide introduce Caddy's config with a JSON config eight brackets deep. Eight! Then it tells you about the API that you might want to use to reconfigure it. Then it tells you about the Caddyfile, but makes clear that it's compiled to the "real" config, and that you'll miss some features in using it.
I briefly look for the JSON reference, and it's nothing like as simple as the Caddyfile. I dig 3 brackets down before to find the configuration for the HTTP server (wait, what, that's just a module now), and there's a lot of boilerplate in that. So there's this mental conflict as I read - the docs say that Caddyfile is _a_ valid way of configuring caddy, but it's clear I'm missing out a true understanding of the program which now has a lot of boilerplate. BOOOOO to boilerplate. Like caddy has spilled its guts into the JSON - the hardwired elegance is a bolt-on. I'm sure this is a lot like how v1 worked, except the v1 docs didn't want me to love its guts.
The v2 docs document Caddy very well, but they sugar-coat the effort of re-understanding a server that old users felt they understood before. It is just not as easy as it was (NB it is still quite easy).
I am happy I can continue using v2 because of the nearly-the-same Caddyfile, but at some point I will have to understand the JSON to really feel in control of my server - maybe that's only 2-3x more work than writing this comment has been :) but that's work the v1 docs never made me do.
You're right about old users, we're not losing sleep over it, we just at least want to lend those users a hand to help them get over the hump to transition to v2. Generally, users should forget everything they knew about Caddy v1 and spend the time to learn Caddy v2 with fresh eyes.
I will say I'm probably the biggest champion of the Caddyfile config language right now, and it's definitely _not_ legacy. It's here to stay. It's just that the v1 Caddyfile hindered the underlying design of Caddy and made it too inflexible. In v1, the Caddyfile was the _only_ config language, and its syntax and design did not allow for flexibility.
For example, in Caddy v1, request matching was not a generalized concept, it was implemented per directive. Each directive had to do its own decisions whether it should apply on any given request, and parse the config for that, etc. In v2, request matching is generalized, and can apply to any directive that is an HTTP handler. Much easier to understand, and much more flexible, much more powerful.
It's true that in v2, the Caddyfile isn't the primary configuration language, but that doesn't mean it's not the users' primary configuration language. The Caddyfile is essentially a layer of magic that maps to the underlying JSON to make it easy to write configs easily and quickly.
Matt decided to explain upfront that JSON is the primary internal config language, because it's important to understanding how Caddy works. It's dangerous to have people run servers without understanding at least a few of the fundamental principles that make them run. That's the purpose of the Getting Started guide, to guide the user through the fundamentals of Caddy so they have a basis of understanding.
Too many people want to go fast and aren't willing to spend the time reading, which is frustrating. Running any kind of web server is a time investment.
I am probably one of those people who would have flamed someone 20 years ago for posting a critique like this without _any_ time to help directly, but I'm not too proud to give you a "moron in a hurry" perspective, because I think it answers your question.
Firstly - maybe do nothing. This is just what losing your old users looks like. They make a lot of noise that things aren't the same, that they're lost, confused etc. and want you to sink a lot of effort into making them comfortable. It's probably not worth it! You know what your success metrics for Caddy look like - so if v2 is succeeding in terms of adoption etc. - just let users go, or trust that they will work it out eventually.
But as one of these muddled users from 5 years ago who has put v2 into production despite the confusion: the v1 docs were brilliant. They were written hand-in-hand with a piece of software that had a target user in mind, and was so clearly hungry for adoption. The Caddyfile remains excellent, an ambitious design to map out what admins truly wanted to configure in a web server, removing everything else.
I think that explains negative sentiment to the v2 docs - Caddy is not built around the Caddyfile any more. So the docs don't centre it, and so caddy doesn't look like it's designed to do the same things. With v1, I felt that as I understood the Caddyfile, I understood caddy, an important and magical new binary on my system. That was almost certainly a flattering lie, but it never faltered. Every experience I had with v1 backed it up.
The v2 docs make clear that the Caddyfile is _legacy_, and that my old understanding doesn't help. The "Getting started" guide introduce Caddy's config with a JSON config eight brackets deep. Eight! Then it tells you about the API that you might want to use to reconfigure it. Then it tells you about the Caddyfile, but makes clear that it's compiled to the "real" config, and that you'll miss some features in using it.
I briefly look for the JSON reference, and it's nothing like as simple as the Caddyfile. I dig 3 brackets down before to find the configuration for the HTTP server (wait, what, that's just a module now), and there's a lot of boilerplate in that. So there's this mental conflict as I read - the docs say that Caddyfile is _a_ valid way of configuring caddy, but it's clear I'm missing out a true understanding of the program which now has a lot of boilerplate. BOOOOO to boilerplate. Like caddy has spilled its guts into the JSON - the hardwired elegance is a bolt-on. I'm sure this is a lot like how v1 worked, except the v1 docs didn't want me to love its guts.
The v2 docs document Caddy very well, but they sugar-coat the effort of re-understanding a server that old users felt they understood before. It is just not as easy as it was (NB it is still quite easy).
I am happy I can continue using v2 because of the nearly-the-same Caddyfile, but at some point I will have to understand the JSON to really feel in control of my server - maybe that's only 2-3x more work than writing this comment has been :) but that's work the v1 docs never made me do.