Documentation quality has been a common complaint. Previously, we only provided reference documentation and relied on the community to create tutorials and guides.
Based on feedback like yours, we've completed documentation rewrite. Have you had a chance to review the new version? Your feedback is taken very seriously, so we'd greatly value your thoughts on these improvements.
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.
We're going to work through these points with the team. Appreciate you sticking with Traefik despite the documentation friction.
Traefik really is awesome once you can get your head wrapped around the configuration.
Once you referenced routers, middleware and services simply by name, but that changed into per-source scoped versions (e.g. service1@file, middleware@docker).
I kept bumping into those edge cases (custom SSL cert set-up was really confusing), but thanks to chatgpt, I at least ended up with workable solutions.
Caddy is probably my new favorite. It works out of the box, its super low resource, handles a ton of traffic, and the docs are decent.
I burned the better part of a Saturday trying to figure out why a relatively straightforward configuration wasn't applying and it's because one half of the configuration that I was trying to apply has to be done in the static manner and not the dynamic manner.
Documentation doesn't really spell this out and after quite a bit of frustrated googling I found a few other people complaining about effectively the same problem. It's only a few lines of code to spit out something along the lines of "hey, you're trying to configure ¢thing in an inappropriate way. Did you mean to configure ¢thing over in €thisLocation?" message... But nope, that would make things so much simpler and easier to use and probably cut into their support contract sales...
Now I basically just stick with nginx because it's documentation isn't crap, useful and applicable examples are all over the Internet.
For k8s, yeah. It should still be a useful tool for other things? Or did i miss a memo about nginx being EOLd?
I also recently started playing around with web UI layer that generates traefik json config. Currently it is quite basic since it was initially made to provide limited time access to development instances but it could in theory manage most important aspects of proxy config and replace something like nginx-proxy-manager. https://github.com/Janhouse/traefik-proxy-admin
To each their own but it's interesting you find it useful (you use it) yet it won't be welcome back. Maybe, as others have noted, try it in Docker (or k3s/k8s/etc). Once the base configuration you want is configured and deployed all you need to do is place labels in for dynamic service configuration.
Nginx which they used before works much better. And these days I use caddy on everything else. That really shines.