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