9 ms·
Traefik is pretty cool, but suffers from the same, terrible problem of Ansible: there is a lot of documentation, and a lot of words written, yet you can never f
by sph 3y ago
Traefik is pretty cool, but suffers from the same, terrible problem of Ansible: there is a lot of documentation, and a lot of words written, yet you can never find anything you need.
I have used it since v1 and I routinely get lost in their docs, and get immensely frustrated. I have been using Caddy for smaller projects simply because its documentation is not as terrible (though not great by any stretch)
Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists, not explanation for different fields spread over 10 tutorial pages. Focus on those that use the product day in and day out, not solely on the "onboarding" procedure.
This is my pet peeve and the reason why I hate using Ansible so damn much, and Traefik to a lesser extent.
- mholt 3y agoFunny you say that because we don’t have nearly any examples in the Caddy docs. We’re working on improving them later this year.
- sph 3y agoExamples are good in docs. But documentation that's only made of examples and tutorials... not so much. Thanks for Caddy btw. Neat little tool.
- linsomniac 3y agoDo not agree WRT ansible, been using it for well over 5 years and usually a google search points me right at the correct part of the documentation to answer my question. Ansible, the tool itself, can be a bit obtuse, largely IMHO because of the YAML source language, so some concepts are hard to translate into the tool, but the documentation has never bothered me. As far as "a lot of words written, can't find what you need", Fortinet is my poster child there (based on trying to use it a decade ago). Everything I looked up there had 10,20,30 pages of introductory material with the Fortinet stuff spread throughout it.
- sph 3y agoAlright, please link me to an exhaustive list of Jinja filters supported by Ansible out of the box. I'll wait. What you are given is https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_filters.html https://docs.ansible.com/ansible/latest/playbook_guide/playb... and you need basically to read/scan each example until you find what you need [1]. Do you call that good, especially when these are basically the only way of doing anything a little complex? That's a sure way of killing my flow and productivity in its tracks. I have been through this page in anger a dozen times, and I still have no idea what Ansible filters can or cannot do. Also, using Google to find stuff is "cheating". The goal of documentation is to be able to use it as reference; if you need an external tool to find anything in it, that defeats its purpose a bit. When people wrote documentation books, they had to make sure it's usable, legible and efficient. These days apparently that's become lost art. 1: these examples are not even exhaustive, because they don't list all the builtin Jinja filters; chances are that what you need isn't listed on that page, but you should instead refer to https://tedboy.github.io/jinja2/templ14.html https://tedboy.github.io/jinja2/templ14.html
- throwaway984393 3y agoI like that it forces users to read the docs to find the functionality. Users don't read the docs, and then they wander around the internet looking for a random blog post with a snippet for one problem, and they don't ever really learn how to use the program. Users are a bit like high school students just skimming books for an answer to fill in on a test. They need to be forced to learn.
- freedomben 3y agoThis doesn't make a lot of sense in the context of the parents. Did you post this to the wrong parent? To accomplish what you are asking, a project needs actual good documentation. Everyone has agreed that is good. The only real disagreement here is whether Ansible docs have this, and regardless whether they do, they definitely have the example-driven docs that I think you are saying you don't think should exist, so you definitely aren't supporting the Ansible status quo.
- throwfaraway398 3y agoIt's funny because one thing I like about ansible is how easy it is to get the reference doc for any module with `ansible-doc -t module`. I do sometimes struggle to find the right doc when I'm searching for something about ansible core itself, but that doesn't happen too often.
- plantain 3y agoMy latest gripe in this category - opentelemetry. Thousands of pages. Very little about actually achieving basic common workflows.
- tnolet 3y agoOh boy that hits home. Been deep in the OTEL world the last months and the official docs are very, very undercooked.
- hooverd 3y agoThe best OTel docs I've seen have been from observability vendors. The CNCF needs some volunteer technical writers or something. I think a lot of those docs suffer from being written by people who know the spec inside and out.
- hinkley 3y ago[flagged]
- silisili 3y agoSame experience. Otel is one of the wordiest docs I've ever come across that says very little. Further, I found a lot of little bugs that are hard to Google, or when Googling finding open issues that are either known and working on, or no response at all. I ended up just throwing it in the garbage and using direct connectors. I like what Otel is trying to achieve, but it feels extremely opaque and half baked at the moment.
- zaphirplane 3y agoYes! Otel, is exactly what I was thinking. It’s for people working on it with access to tribal knowledge. For mortals working to add it to their service it’s not fit for purpose
- jackthejacky 3y agoOh man, I FEEL this comment. That was one absurdly awful set of documentation, because they not just have a lot of confusingly placed repeat content, they also follow the philosophy of only explaining top level initial conceptual primer for everything, and only explaining the actual main use case of the component 3 navigation pages deep. So a beginner has to jump a BUNCH of pages to get a primer, and an expert has to bookmark the couple actually-useful pages and later give up and just look at github for specific operators/processors when they already know the basic config inside out.
- deepersprout 3y agoI usually feed all the documentation to an llm and ask the question to the llm that fetches the info with rag. For example: > how do i configure Traefik to proxy traffic to two backend services? Configuring Traefik to proxy traffic to multiple backend services is a common use case. You can achieve this by defining multiple entry points and routers in Traefik's configuration, each pointing to a different backend service. Here's a basic example of how you can configure Traefik to proxy traffic to two backend services: yaml # traefik.yaml # Enable API and Dashboard api: dashboard: true # Define entry points entryPoints: web: address: ":80" app1: address: ":8081" app2: address: ":8082" [...more stuff...]
- san-fran 3y agoThis might be an additional way to quickly iterate on the content of the documentation itself. If I were the one writing, an easy test is passing the documentation to a lay person and asking them if they have what they need to perform X by following the documentation. Perhaps having a focused LLM generate the steps could help catch some documentation deficiencies.
- freedomben 3y ago> If I were the one writing, an easy test is passing the documentation to a lay person and asking them if they have what they need to perform X by following the documentation. What kind of documentation is this though? Is this how to bake a cake or tie a necktie, or is it how to setup a reverse proxy for the services in your k8s cluster? If it's something a lay-person could do then I think this is a good strategy (though depending on the size/scope of the project/documentaiton it does seem like a pretty big effort to undertake without compensation), but if it's something highly technical like Traefik, I expect a lay-person to not even understand half the words/vocabulary in the documentation, let alone be able to perform X by reading it and following it.
- all2 3y agoIf we push this into the software development domain, my expectation would be something like "documentation should allow a software developer to do this thing without knowing the underlying tooling". > how to setup a reverse proxy for the services in your k8s cluster Going off this specifically. I don't know how to do this. I actually have a k8s cluster on a home server waiting for me to do exactly this. Ideally there would be a doc that would start with ingress selection, and then guide a user through how to get it set up with common use-cases. Or something like that. Like others in this conversation, I've been leveraging LLMs with varying degrees of success to try and navigate this.
- johanbcn 3y ago> Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists, not explanation for different fields spread over 10 tutorial pages. Focus on those that use the product day in and day out, not solely on the "onboarding" procedure. I agree. We all would benefit by giving more exposure to documentation frameworks such as https://diataxis.fr https://diataxis.fr
- adolph 3y agoI'm glad to have clicked through for curiosity's sake. Diátaxis is tremendously interesting. For folks who might recognize the author's name: Daniele Procida: Director of Engineering at Canonical. Creator of Diátaxis and BrachioGraph. Django core developer. Fellow of the Python Software Foundation.
- yoyojojofosho 3y agoDiscussed on HN: https://news.ycombinator.com/item?id=33721314 https://news.ycombinator.com/item?id=33721314
- siamese_puff 3y agoAlso https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/
- FelipeCortez 3y agoThese are "the same". Diátaxis is the fork the author made after (I presume) they left Divio.
- siamese_puff 3y agoAh TIL
- deleted 3y ago[deleted]
- 3y ago
- lopkeny12ko 3y agoThis take is, at best, disingenuous, and at worst, dangerous. The Traefik maintainers and community contributors (including myself) have collectively invested hundreds of man-hours writing and improving documentation, specifically in response to feedback from users that things are hard, unintuitive, or complex. You are discounting massive amounts of unpaid labor done specifically for people like you. At this point, if you can't find what you're looking for, it's on you. Maybe do a little bit of your own homework instead of throwing your hands up after 2 minutes and crying to the maintainers.
- alex_lav 3y agoInvesting a lot of time and trying really hard is not the same as adding a lot of value. If your users don't find value in your documentation, saying "But we spent a lot of time on it!" doesn't really change anything. And, to be clear, I have no idea if the person you're responding to's criticism is valid. But I also know that your response does not negate their criticism at all.
- lopkeny12ko 3y agoHow about submitting a PR to improve the documentation instead of complaining about it?
- Thiez 3y agoThis is why OSS looks like a cult at times. People are allowed to criticize your project and complain about it. They have no obligation to become a contributor. "Submit a PR" is such a conversation killer.
- alex_lav 3y agoYour adversarialism isn't a good look. Users are allowed to have opinions, this does not mean they have maintain the work themselves.
- joshmanders 3y agoCustomer: I can't find anything I'm looking for in your store. Store: I spent a lot of time arranging things around in the store, if you can't find what you're looking for you can stop complaining and write signs for us. Customer: Or I can just use your competitor who actually cares about their customers. ¯\_(ツ)_/¯
- igor_varga 3y agoI'm using the Traefik and have the same experience with the documentation. It can be time consuming to configure it properly if you are not a power user. I'm happy with it though, it's a great piece of software. I wonder is there any other product out there with a similar feature set?
- lamontcg 3y ago> Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists, not explanation for different fields spread over 10 tutorial pages. Focus on those that use the product day in and day out, not solely on the "onboarding" procedure. You really need at least three documentation targets: - onboarding the newbies workflows/tutorials - intermediate "focus on the important bits" workflows/tutorials - exhaustive references There might be other useful ones as well, but I never see those three hit at the same time adequately.
- hinkley 3y agoSome projects need documentation, some need cookbooks. Sounds like traefik is the latter. Hopefully as an aside (I know very little about traefik so maybe I am talking about them too and don’t know it), it seems like in the time since I abandoned Java they have weaponized that architectural strategy and I have no patience for it. I look at that sort of documentation and my eyes glaze over. Or if they don’t I feel disgust or anger and all three result in my stomping off. Opentelemetry, particularly the stats code (vs the span code) triggered a lot of this in me. It has several sets of documentation that say different things. It took me a long time to figure out how to connect the amorphous dots, and then I didn’t entirely agree with their solution anyway.
- remoquete 3y agoOpenTelemetry docs maintainer here. We need more quality feedback like this. Please consider contributing issues to the docs repo.
- jethro_tell 3y agoOne of the problems that the yaml interpreter class of languages, or whatever you'd call them, suffer from is the fact that yaml itself is a language and tends to be more or less undocumented in the interpreter docs. It's sort of assumed that you are going to do extremely simple tasks on very flat data structures. That doesn't tend to be the reality that most of us live in. And to really get the most out of these languages you have to understand an entire unspoken set of rules on how to use yaml. That's never really pointed out in the docs. Additionally, there are docs for the unique settings for each module but as far as using the standard settings, additionally, its rarely clear how to operate on the data that might be returned or combined with anything mildly complex, you are given a dozen 1 stanza examples for each item like a stack of ingredients and then told to bake a cake. I've had this experience with basically every one of the various yaml interpreter systems I've used. After a few 100k lines of yaml I can get things done but the docs are useless other than a listing of settings.
- ornornor 3y agoTo illustrate this point, here is how to have a multi line value in yaml: just kidding, it’s so confusing that there is a whole website to help you figure it out: https://yaml-multiline.info/ https://yaml-multiline.info/
- hombre_fatal 3y agoThose examples don’t look confusing except there being more than one way.
- ornornor 3y agoGood luck remembering which is which :)
- cromka 3y agoIsn’t it why toml is seemingly increasingly used to replace yaml in projects?
- bshacklett 3y agoThis was exactly my experience. It’s incredibly frustrating to search documentation only to be stuck with examples that are related, but don’t fit one’s exact situation, and don’t explain the underlying behavior.
- cdelsolar 3y agoIf only there were a program that had crawled bazillions of documents, including all of the traefik documentation, examples, and thousands of code files using it, and if only said program were especially designed to answer natural-language queries about said documents.
- Fire-Dragon-DoL 3y agoI want both, in the same page if possible, for every possible permutation of input arguments. In theory ansible does this, but then it doesn't link to "you might use it in combination with...", essentially, it lacks integration of multiple things in the reference docs. but I didn't find ansible docs that bad? Most of the time I search module name and find the reference doc
- scrubs 3y agoOh man are you on to something!!! One huge, bad side effect of web is the atomization of an overall body of work into 62.9 million links. One pdf please. The book concept works! You know who's docs blow too? Mellanox. I hate their stuff. And to give credit where due: intel does a damn good job.
- arendtio 3y agoI agree that the documentation could be better, but it isn't that bad. I enjoyed all the gophers, and these images really helped me understand the structure. However, I find it amusing that you wish there was a better reference. I think getting to the initial setup is quite hard. Once you have that, extending it is straightforward.
- samuell 3y agoAnsible is definitely requiring constant lookup in the documentation. I've found a pretty good workflow with using ansible-doc though, with two-three aliases that I use constantly: alias adl='ansible-doc --list' alias adls='ansible-doc --list | less -S' alias ad='ansible-doc' Then I'll: 1. Use adls to quickly search (in less with vim bindings) for relevant commands, 2. Check up the docs with `ad <command>`. 3. Almost always immediately jump to the end (`G`) to see the examples, which typically provides a direct answer to what I need. Since authoring Ansible scripts is so dependent on the docs, I think they really should make this process work better out of the box though, providing some interface to do these lookups quicker without a lot of custom aliases.
- bithaze 3y agoI keep the module index[0] in my bookmarks bar and that's also been pretty easy to search and read. [0] https://docs.ansible.com/ansible/latest/collections/index_module.html https://docs.ansible.com/ansible/latest/collections/index_mo...
- rezonant 3y ago> Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists, not explanation for different fields spread over 10 tutorial pages. Well said, this extends far beyond Traefik. Far too much documentation these days is tailored for people who have never used software of it's type. This was a workable strategy during the Great Developer Boom, but that's more or less over now. As a developer who didn't come from this Boom, I have been constantly frustrated by this trope, and I hope the changes in the industry will tip the scales back toward solid reference documentation, so that I can feel confident in deploying more of these technologies. Putting that more general note aside, I have been a Traefik user for years and I do recommend it. But a lot of what it does is difficult to cite using solid docs.
- sharperguy 3y agoI've often resorted to just looking through the project on github and finding whatever source file is responsible for parsing the configuration files to figure out what each option does.
- _lvbh 3y agoThis applies nearly universally in open source. If documentation isn’t sufficient, jump into the source code and most things can be figured out. Reading other people’s code is also a great way to learn/experience different approaches
- mubu 3y agoI share the same sentiments. I dread having to go through Ansible docs because it's so densely packed. Meanwhile Caddy's docs feel too sparse, and too many spread out tutorials. The reference isn't well thought out either imo.
- mholt 3y agoWe're revamping the Caddy docs this year.
- ollien 3y agoPydantic falls into this box for me. The maintainer refuses to build API reference documentation, as they feel that there should only be one source of information. It's their project, of course, but every time I need to find a method on an object, I am scouring pages of prose for it. Sometimes it's just easier to read the source.
- aeyes 3y agoWhat's missing from the existing API documentation? https://docs.pydantic.dev/latest/api/base_model/ https://docs.pydantic.dev/latest/api/base_model/
- ollien 3y agoOh nice! I'll admit, my comment was based on outdated knowledge (the last time I used Pyandtic for a major project was in 1.x). https://github.com/pydantic/pydantic/issues/1339 https://github.com/pydantic/pydantic/issues/1339
- angra_mainyu 3y agoHaproxy does the whole documentation side of things very well. The docs are very straightforward and thorough.
- molszanski 3y agoThis is strange. I also don't like the docs but for a different reason. I would rather have a more examples. And kinda _advanced_ and complex, rather than trivial we see in the docs. Even though I had a working V1 configs and had a know-how about lingo / architecture like routes / services I still struggled for a day or two to properly configure a pretty simple workflows in v2 like: * add TLS with LetsEncrypt * configure multiple domains * configure multiple services * add Basic Auth for some domains That said, more detailed and extensive docs would be much better. I also remember finding things in github issue comments that worked as bugfix/workaround of something from the docs. PS. For now I've moved to Caddy for simplicity and better Caddy DSL compared to yaml/label verbose config.
- crabbone 3y agoJust another one for collection: conda. Especially the parts about conda-build, meta.yaml etc. There are only examples w/o any way to tell what's available. And the source code is frustratingly twisted, undocumented and all over the place. Something that makes creating conda packages an extremely frustrating experience, to the point that it's significantly easier to create archives and write the metadata by hand than to rely on conda tooling.
- DanielHB 3y agosame reason why Terraform AWS Provider is better documentation than AWS documentation https://registry.terraform.io/providers/hashicorp/aws/latest/docs https://registry.terraform.io/providers/hashicorp/aws/latest... If I can't find the answer to what I need there I usually resort to LLMs, they are surprisingly good and fetching the info you need out of these massive documentations. The failure rate is quite high though so a lot of trial and error required, but the LLM at least gives you some hints to where to look for it.
- danielvaughn 3y agoMy primary use case for LLMs so far has indeed been to avoid terrible technical documentation.
- walthamstow 3y agoI'm on the lookout for an LLM that is relatively small and focused on technical documentation. I don't need it to write prose or haiku, just answer my questions based on documentation
- danielvaughn 3y agoYep. Build it into an editor and I'd be the first customer.
- SoftTalker 3y agoI don't think ansible docs are that bad. I use duckduckgo and adding !ansible to my search usually gets me what I need pretty directly.
- pragma_x 3y agoPossibly unpopular opinions to follow. This is made even worse by: - Having documentation split between v1 and v2, that is similar yet different enough to yield half-baked configurations before you realize what you did wrong. The website itself provides the barest of subtle changes to distinguish the two. Edit: I learned all this prior to v3. - Supporting multiple config formats (TOML and YAML) which makes it that much harder to hunt down relevant forum posts for support. That wouldn't be a huge problem if it weren't for things that you need that aren't in the documentation (above) - Multiple configuration _modes_. You can set options on the CLI, or in config files, and they are not 100% reflected between the two; some things must be in config files no matter what. Config files themselves are split between "dynamic" and "static" configs, and you must place the correct options in the right file. - The one thing that Traefik does well is routing traffic to/from containers. Container labels are used to drive this. How to map those label namespaces to various internal and user provided aspects of Traefik is unclear in the docs, at best. - Traefik exposes a dashboard web GUI by default. Yet much of the useful diagnostic and troubleshooting information is only found in the container logs. Retiring v1 completely, picking a single configuration language/mode, and providing a rich library of example docker-compose configs, would go a very long way to securing this project's future.
- renk 3y agoThe documentation split is unfortunate and the GUI really just a status page. The other points are a strength. A pattern that works well: Put all Traefik config in your Docker container definitions, as command line flags and labels, plus the dynamic config provided as a volume. That gives you all the flexibility and only one or two places to look for the config (e.g. a Docker compose file and the dynamic config file)
- pragma_x 3y agoWhen done right, I appreciate that Traefik's config design meets the container config/run time split pretty well. I also get that we're arguing TIMTOWDI vs YAGNI. So, I want to take a beat to say that I think your take is absolutely valid, but I'm coming at this from a place where flexibility isn't my primary concern. I'm usually more interested in tools that will reliably save me time, and that's a quality typically in opposition to flexibility. For me, any tool that requires or permits multiple configuration planes to get off the ground threatens to be a time sink and a tax for an already packed schedule. This complexity usually requires the operator to absorb a lot of nuance, quirks, and idioms, which is something that's difficult to do quickly. Troubleshooting also grows in scope , again due to the complex design and multiple ways to set things up. Meanwhile, the most inflexible tools in my stack cause me the least trouble due to their simplicity: there's one way to do it, and if it's a common mistake, the answer is easily searched online. In practice, looking to the Traefik community for support required decoding everyone's different take with varying degrees of CLI and config file involvement, sometimes fragmented across entire discussion threads (not to mention the v1/v2 problem). It made for a very time consuming troubleshooting run - something that would have been avoided by a more simple design like other tools use.
- Propelloni 3y agoFrom this point of view the Oracle RDBMS handbooks ca. 1998 were pretty good. Come to think of it, they were pretty good all around.
- jq-r 3y agoThose are great points. Even the page layout of the documentation is terrible. Whywe have huge monitors and millions of pixels if I have to read content from a very narrow column, which is a mile long? Eg: https://doc.traefik.io/traefik/routing/services/ https://doc.traefik.io/traefik/routing/services/ If you visit that page in your desktop browser you'll get less words per column then seeing this on the iPad (works even in dev tools window). Mind blowing.
- remoquete 3y agoYou're assuming that Traefik has a team of technical writers taking care of the docs. From what I know, that's not the case.