Configmgmtcamp 2024 was a blast. There were a lot of great sessions and sharing of ideas. One piece of feedback that came up was to expand the use of the “See also” section in module documentation.
If you’re not familiar, the “See also” section points out modules that have similar functionality but for different use cases or, sometimes, for different platforms. It is a convenient way to disambiguate similar modules but also to group related modules that build and expand on each other’s functionality.
It can often be the case that you start using one module with a certain goal. However the module that you are using is only related to that goal but not specifically intended for the purpose and is not the best thing to use.
You can find an example of the “See also” section in the ansible.builtin.copy module documentation.
So what can I do, you ask? Do you have any examples of modules in collections that could benefit from a “See also” section? Let us know!
You can reply to this thread with any ideas for pointing out good candidates for a “See also” section in module docs. We can then try and work with the collection owners to update their documentation.
This provoked some interesting conversation because your suggestion expands the “see also” section beyond Ansible documentation to more general technical resources, like the Wikipedia INI page. There might even be a blog post or two in there!
Over the next week or so I’m planning to break your suggestions into GitHub issues so we can track the updates and hopefully get some community contributors to participate in applying them. However I’m holding off a bit longer until the next edition of the Bullhorn. I included this forum post in an update and am hopeful we might get some more excellent suggestions. So stay tuned!
I just want to say that I love the seealso section in docs and use it a lot in the public collection I maintain and also in the private internal collections I work on.
I also use this. It can be direct web links, but it’s also a good thing to keep in mind that one of the entry types is for general RST references.
Since we use intersphinx, and the ansible collection docs specify a few other sphinx sites, we can link to those with direct references, for example to python or jinja documentation (this is also how collection docs can link to the main docsite pages without using hyperlinks).
To give an example, in one of my internal collections, I have this entry that links to Jinja2 docs (alongside an entry to the main ansible docs):
seealso:
- plugin: ansible.builtin.version
plugin_type: test
- ref: builtin-filters
description: See the Jinja2 C(select) built-in filter.
I’ll give some of the regular docs contributors a chance to handle the issue but will send the PRs myself if nobody else takes it on. If it’s OK with you I’ll give you the “co-authored by” attribution in the commits too. Cheers!
