[linsomniac]

Do 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]

Alright, 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/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

[freedomben]

I'm not GP, but I agree with both them and you so thought I'd chime in.

You're absolutely right that there are big omissions/holes in the Ansible docs, but I also think that using Google is not "cheating." My ideal of great documentation sounds like exactly what you would agree with: A complete and comprehensive "book" (could become a physical printed book, but needn't have to as it should be equally usable with good old-fashioned hyperlinks). It should have a logical flow, introductory sections to describe pre-requisite knowledge/concepts and things that are broadly applicable to the project as a whole. It should have a table of contents, and it should definitely have an index and comprehensive lists/tables of API details such as available field/properties, which options are valid (for enum fields), etc. Your example of Jinja filters supported by Ansible is a great one. I really miss the 90's era here where such manuals were common practice, even for things like PCs.

With that ideal described, though, I think it's important to recognize pragmatism and feasibility. Documentation takes time and money to produce. Search tools (including Google) already exist and can provide a valuable addition without spending time/effort on it, so I think they should be used. That said, I agree that it's not a good idea for doc writers to rely on that for things to be found! Table of contents, logical flow, and indexes should absolutely be thought through. If the documentation is just a bunch of random unorganized and uncatalogued pages that can only be found with a search engine, that is really bad and they should feel bad.

I think Ansible falls right in the middle there. It undoubtedly has some real glaring omissions/holes in it, but it is also not nearly the worst I've seen as well. I do dread having to go the Ansible docs though, which is an indictment against their quality, and the more I think/write about this the more I agree with you lol.

[linsomniac]

As you say, Ansible's filter list does not include the base Jinja2 filters, which I guess is a difference of opinion. I feel that is preferred to reproducing the Jinja2 documentation, especially as the Jinja2 filter list is the first (non-TOC) link on the page.

Also going to disagree about "using Google is cheating". The purpose of documentation is to help me get stuff done. The Internet is not printed on dead trees, I don't want to read through a TOC or index looking for what I want when I'm searching, I want to use a search engine. I often don't want a reference, I want to quickly find how to do something. I rarely want to read about all the filters, instead I want to find the even/odd filter, or the the default or omit filter. Yes, sometimes I want to brush up on all available filters, but that's rare.

[SoftTalker]

Maybe you use ansible in a more complex environment than I do. I use ansible to provision servers, and jinja2 filters are some of the least-used things for me. I try to keep my ansible roles short and simple, and needing obscure jinja2 filters is a clue to me that I might be getting too fancy.

That said, when I have a question about jinja2, I find that the jinja2 docs are better than the ansible docs.

[throwaway984393]

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

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

[coryrc]

The rest makes more sense if you assume parent post meant to write "read the code".