Live data from Hacker News

Take a look at Traefik, even if you don't use containers

j6b72.de

201–210 of 266 posts

Re: Take a look at Traefik, even if you don't use containers

#201
post #52

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 wr…

same reason why Terraform AWS Provider is better documentation than AWS documentation

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.

Re: Take a look at Traefik, even if you don't use containers

#202
post #199
post #194

Earlier quoted context omitted.

Pydantic 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.

What's missing from the existing API documentation? https://docs.pydantic.dev/latest/api/base_model/

Oh 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

Re: Take a look at Traefik, even if you don't use containers

#203
post #52

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 wr…

same reason why Terraform AWS Provider is better documentation than AWS documentation 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 give…

My primary use case for LLMs so far has indeed been to avoid terrible technical documentation.

Re: Take a look at Traefik, even if you don't use containers

#204

Earlier quoted context omitted.

same reason why Terraform AWS Provider is better documentation than AWS documentation 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 give…

My primary use case for LLMs so far has indeed been to avoid terrible technical documentation.

I'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

Re: Take a look at Traefik, even if you don't use containers

#205
post #52

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 wr…

My latest gripe in this category - opentelemetry. Thousands of pages. Very little about actually achieving basic common workflows.

I feel like it is endemic to anything OPS / DevOPS. Lot of uselessly verbose "documentation" but no list of whatever you really need.

All in the name of selling products which abstract those parts, consulting or courses.

Re: Take a look at Traefik, even if you don't use containers

#206
post #52

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 wr…

Ansible 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 `. 3. Almost always i…

I 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_mo...

Re: Take a look at Traefik, even if you don't use containers

#207

Earlier quoted context omitted.

I hope not, toml is even worse at complex things and just slightly better at the stuff that isn't confusing. Add a k:v to a mildly complex dict. At this point, I'm pushing into a place where I'm just going to switch to go because its getting to be a mess.

It’s insanely better at config. It’s about as bad at being a programming language or data structure serialization format, though.

Nope it isn't.

There are so many things that aren't expressible in TOML that any anywhat complex system will want... it's not even a contender.

So, one problem a lot of configurations are trying to solve: modularity. I.e. how to allow different actors to change the parts of the configuration they want. Everything under /etc nowadays is of a form /etc/*.d/*.* that is all configurations are directories of multiple files with some ridiculous rules (like "prefix file names with digits so that they sort and apply in the "right" order etc.) XML had a better approach with namespaces and schema, but maybe not perfect.

Polymorphism. Any non-trivial configuration system will have plenty of repeating parts. NetworkManager connection configurations? -- They are all derived from the same "template". Systemd device services -- same thing, they are all coming from the same "template". There are plenty more examples of this. But, languages like YAML or TOML don't have a concept of polymorphism in them. This is never encoded in the configuration itself. Instead, every tool that needs to be configured and needs some degree of polymorphism rolls its own version.

Constraints. It's often impossible to describe the desired configuration through specifying the exact values. Often the goal can be described as "less than" or "given the value of X, Y should be multiple of X" and so on. Such concepts, are, again, not expressible in TOML or YAML and friends.

NB. Types are a kind of constraints.

Identity. It's often necessary in configuration to distinguish between two sub-sections that look the same and two sub-sections that designate the same exact object. Like, when configuring VMs with eg. disks: are they supposed to mount the same disk, or does each VM need a separate disk, that just has the same physical characteristics?

Re: Take a look at Traefik, even if you don't use containers

#209

Earlier quoted context omitted.

> 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 ht…

Also https://docs.divio.com/documentation-system/

These are "the same". Diátaxis is the fork the author made after (I presume) they left Divio.

Re: Take a look at Traefik, even if you don't use containers

#210
post #52

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 wr…

I 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.

Post reply on HN