Hi there. I'm a brand new Traefik user. It's bundled with k3s, so I set it up for my homelab on a single node cluster. I'm a technology professional who has worked in infrastructure and software roles for more than 15 years.
I appreciate that you revised the docs, but I still found it quite difficult just to get started. My experience was poor enough that I almost switched to Caddy. The thing that kept me from doing that is that Caddy requires a custom container build for DNS-01 ACME challenges which I didn't particularly want to deal with. I found Caddy's documentation much easier to grapple with, so that could serve as some inspiration.
I have some feedback I'd offer of my own, too:
1. I'd recommend you take a look at the Divio documentation system: https://docs.divio.com/documentation-system/. Your documentation aligns to this vaguely, but I'd recommend reading about the different doc types and applying that feedback throughout the docs.
2. Traefik's tutorial and how-to docs are very dense and feel overwhelming. [1] Related to my first point, I think you're trying to provide too much information in the wrong places. Tutorials and how-to guides should be very focused and limit explanation to only that which is absolutely necessary.
3. Reference and understanding docs are mixed together. I'd recommend using an approach more like Caddy's, where the config reference (https://caddyserver.com/docs/json/) shows prominently what the expected config schema is, and all of the fields are explained briefly. If there is very nuanced behavior for a particular option, consider moving that to a separate reference or explanation page.
4. Having a few How-To guides for the most common patterns which include complete configurations would be helpful.
[1] Here are some concrete examples:
- On https://doc.traefik.io/traefik/setup/kubernetes/, there is a whole introductory session about setting up Kubernetes and I have to scroll before reading anything related to Traefik. It's not only unnecessary -- it's noise. Nobody is going to consult Traefik's docs for setting up Kubernetes, so just omit it.
I appreciate that you revised the docs, but I still found it quite difficult just to get started. My experience was poor enough that I almost switched to Caddy. The thing that kept me from doing that is that Caddy requires a custom container build for DNS-01 ACME challenges which I didn't particularly want to deal with. I found Caddy's documentation much easier to grapple with, so that could serve as some inspiration.
I have some feedback I'd offer of my own, too:
1. I'd recommend you take a look at the Divio documentation system: https://docs.divio.com/documentation-system/. Your documentation aligns to this vaguely, but I'd recommend reading about the different doc types and applying that feedback throughout the docs.
2. Traefik's tutorial and how-to docs are very dense and feel overwhelming. [1] Related to my first point, I think you're trying to provide too much information in the wrong places. Tutorials and how-to guides should be very focused and limit explanation to only that which is absolutely necessary.
3. Reference and understanding docs are mixed together. I'd recommend using an approach more like Caddy's, where the config reference (https://caddyserver.com/docs/json/) shows prominently what the expected config schema is, and all of the fields are explained briefly. If there is very nuanced behavior for a particular option, consider moving that to a separate reference or explanation page.
4. Having a few How-To guides for the most common patterns which include complete configurations would be helpful.
[1] Here are some concrete examples:
- On https://doc.traefik.io/traefik/setup/kubernetes/, there is a whole introductory session about setting up Kubernetes and I have to scroll before reading anything related to Traefik. It's not only unnecessary -- it's noise. Nobody is going to consult Traefik's docs for setting up Kubernetes, so just omit it.
- https://doc.traefik.io/traefik/setup/kubernetes/ and https://doc.traefik.io/traefik/getting-started/kubernetes/ are different pages which seem to explain mostly the same things. They both include too much irrelevant information, like overly explaining what Helm commands do. Similar to the previous point, it is not the job of Traefik's documentation to explain Helm to me.