We get off-hand comments like this about the docs on occasion, and without explanation, we can't do anything to improve the docs to resolve the complaints.
We put in a ton of effort on the docs, and we think they're great. What are you missing? Did you spend the time going through and reading the docs?
I'm actually a recent Caddy convert, and only picked it up after I saw the v2 GA announcement here on HN. I'm also not using it at large scale: it's just the frontend reverse proxy for my home infra, which is itself frontended by CloudFlare's strict-level DDoS protection/proxy.
I set everything up a few months ago, and my pain with the documentation was that it tended to only address the extremes of dead-simple Cadddyfile examples or very intricate JSON reference. Given that I was working with CloudFlare, thinks were a little more complicated: I had to setup my own Dockerfile to recompile against the externally-maintained CloudFlare module (which, btw, thank you to ever maintains the builder container for making that dead simple with Docker's copy feature). Then some more extra stuff in the Caddyfile to pass in the API key, as well as to work properly with a totally different cert sitting on the web server I was reverse proxying.
That being said, I came back this last weekend to fix up some other stuff, and it seemed like the docs were more complete in general. I found a lot of Caddyfile reference that I needed very easily. So either discoverability or content was improved, or I was just not acquainted enough with Caddy to find it last time (which is totally possible).
And just 2cents from a user who also PMs some OSS software: mad respect for being out here and asking these questions. I completely feel how hard it can be to get anyone to answer this in good faith, and the slow build of anxiety that comes in seeing vague complaints like this littered throughout the internet. Even if I know that they don't mean it personally, it can get me very worked up, especially after many years of reading it.
And yet, doing it repeatedly is the only way to know wtf to improve. I can completely relate with Caddy on the telemetry stuff too, God knows that's an even more difficult sell.
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.
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.