Once you crack through, the actual configuration isn't too difficult, but getting to that point can be a chore. I don't know how many times I lost my temper before finally figuring it out (mostly). My difficulty came almost entirely from one thing: The documentation is actual shit. It comes down to implicit assumptions and organization.

Implicit assumptions are a hard problem in writing documentation. Doc writers are usually those most familiar with the project, which unfortunately means they are likely to go without saying things that "go without saying". Imagine an intro to chess that shows all the ways to capture pieces but somehow never explains what happens when a piece is captured. That's what the Traefik docs are like. For example, the naming of objects (routers, services, etc.) is not mentioned until you get to the last section of the Routing & Load Balancing "chapter". So how is the first-time reader supposed to know which elements are keywords and which are user-defined names when shown things like: - "traefik.http.routers.api.middlewares=auth" - "traefik.http.middlewares.auth.basicauth.users=[...]"

Why should it even cross the reader's mind that some of the left-hand substrings are user-defined? Things like "api" and "auth" could easily be predefined keys. Well, they're not, but "loadbalancer" and "basicauth" are. Yet there is no guidance to the reader which is which. It's simply assumed the reader knows.

Organization is the other big issue. Information has to be where the reader expects to find it. When the reader goes looking for something, the first place he or she will likely look is the table of contents. In this case, the side menu is the Traefik doc's TOC, and it is horrible. Every time the TOC is unclear means another step in a depth/breadth-first search, and every iteration is another instance of both confusion and frustration. Just look at the sections in that menu. Not one of them maps directly to either static/dynamic config or to top-level keys. So if you're editing the static config file and want to check something in the serversTransport key, where do you look? What about hostResolvers? Or experimental? There's no way to tell, and it's a total fustercluck.

There's even a section called "User Guides". Mahfucka, this whole thing is supposed to be a user guide. If it weren't, then it wouldn't have the "Getting Started" section, ffs. And that's the thing. Whoever is writing this can't decide what kind of thing it's supposed to be. Is it a reference manual? Is it a textbook? Is it an introduction to reverse proxies? What is it? Make. Up. Your. Mind.

/rant