Hacker News Reader

Comment by mattbee | Hacker News Reader

The docs were brilliant for v1, it wouldn't surprise me if they were the spec for a great user experience and the code came second.

Despite v2 supporting a very similar config file, the documentation doesn't emphasise that and tries to steer you towards its API, confusing JSON config syntax etc.

It's still a very good web server for very few lines of config, but I don't relish trying to learn something new from its docs like I used to.

View on HN

> and tries to steer you towards, its API, confusing JSON config syntax

I disagree. The docs don't do that. What you're probably talking about is the Getting Started guide https://caddyserver.com/docs/getting-started, which is a tour of how Caddy works, so it first shows you the "bare-metal" look at how it works, then it introduces the Caddyfile which allows you to simplify your user experience.

There's even a comparison table between the two https://caddyserver.com/docs/getting-started#json-vs-caddyfi... which explains when you'd want to use JSON (i.e. if you want programmable, API-based usage) or Caddyfile (i.e. for quick-and-simple hand-written config, 95% of users choose this).

I recommend starting from https://caddyserver.com/docs/caddyfile-tutorial or https://caddyserver.com/docs/caddyfile/concepts to get an idea of how the Caddyfile works.

That might be true now, but I spent a lot of time trying to use caddy v2 and not being able to since the only docs where for json and some things where available in caddyfile and some in json.

If it is fixed now then that is great, but it took at least a year (I'm guessing more) after the launch of v2.

Of course it wasn't going to be perfect at the initial release, nothing ever is. Caddy v2 was a complete rewrite from v1, so there was a lot of TODOs to polish it up.

Definitely take another look now, there's been a ton of progress since then, 3 years ago. The initial v2 release was in May 2020, soon after the pandemic hit.

> Of course it wasn't going to be perfect at the initial release, nothing ever is

What I'm trying to say is that on launch v2 was not a good replacement for v1, especially in the docs area. I've seen quite a few major version bumps in OSS, and it feels docs is an area that is usually neglected, and for quite a while (at least a year, I'd say more) the v2 docs where not useful for someone who had not participated in the caddy v2 community discussions.

I'm just trying to describe what led me to go from a avid caddy proponent back to an nginx user.

I'll take another look next time I have a project that needs a http/s server!

> Now you know that the Caddyfile is just converted to JSON for you.

> The Caddyfile seems easier than JSON, but should you always use it? There are pros and cons to each approach. The answer depends on your requirements and use case.

Followed by a table comparing the json and caddyfile approaches. What's the confusion?

> The docs were brilliant for v1, it wouldn't surprise me if they were the spec for a great user experience and the code came second.

I agree with this, v1 was an excellent user experience, I actually ran it on my servers for way too long. There was also the Wedge fork which might have helped with the EOL but sadly it didn't go anywhere: https://github.com/WedgeServer/wedge

> Despite v2 supporting a very similar config file, the documentation doesn't emphasise that and tries to steer you towards its API, confusing JSON config syntax etc.

Others responded to this a bit more, but while I agree that different config types are a confusing experience, at the same time I appreciate that they support something like that in the first place. I might not use it often, but it's nice that you can.

It's almost like the docs were written for someone upgrading from V1 (or familiar with V1) instead of a newcomer who knows nothing (like the V1 docs were written for).

That's not true. The docs are written with the expectation that the user understands how the web works. We can't reasonably teach that in our docs. Instead, users should read MDN for that stuff. If you were coming from v1, the only page that makes that assumption is the upgrade guide https://caddyserver.com/docs/v2-upgrade. Everything else is either a getting started guide, a tutorial, or reference docs for Caddyfile and JSON config.

I didn't say it was true, I said it just seems like it. As an example: https://caddyserver.com/docs/caddyfile/directives/php_fastcg... -- it shows the syntax, but nowhere on the page does it tell you WHERE to put it in the config file. Is it top-level? Do I nest it in something else? Keep in mind, most people are starting with a mostly blank file, and zero context about how Caddy works (whether or not they understand how the web works). This page won't answer the basic questions of where it is allowed, and neither will the getting-started docs, which tells you to make a json file instead of a Caddyfile but the docs for the thing I looked up doesn't look like json (maybe I know this, maybe I don't). It's all very confusing for someone looking in the docs for a solution and instead has to learn how everything works, whether they want to or not.

That's what this page is for: https://caddyserver.com/docs/caddyfile/concepts#structure. You shouldn't be reading directive docs before the concepts page. The directives page https://caddyserver.com/docs/caddyfile/directives at the top also tells you where these go, which is where you must have came from to find that directive's page in the docs. The information is all there, you just need to read it. Read things in order, don't skip steps; don't skip steps in the getting started guide either, that defeats the purpose of the tour it gives you.

Google is not going to take me to that page first when I search for how to do something in Caddy. It's going to take me to the directive, most likely.

To say it again:

> It's all very confusing for someone looking in the docs for a solution and instead has to learn how everything works, whether they want to or not.

How can we fix this without repeating the Concepts page on every page of our docs?

Maybe we should just un-index all docs pages except the intro pages.

I think there are several ways to handle that. Assuming you are using templates for the docs:

1. A simple link like this: https://docs.k3s.io/installation/configuration#:~:text=For%2....

2. An aside at the top that informs the person where to get more information with a link.

3. An example showing the structure of the file.

4. A link to examples/tests in the repo showing how it can be used.

I would think that a simple aside in your template would work wonders. Maybe saying something like:

> See our page on [directives](link) to learn how to best use this in your configuration.

Reply on news.ycombinator.com