Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: