Call to action: Send us your "see also" suggestions

Hi!

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.

7 Likes

Great idea, I’d also like to see more examples adding to pages perhaps another thread for that would make sense?

INI / CONF

The .ini / .conf file lookup, fliters and modules could be linked:

And also the JC INI parsers that can be used with the JC filter:

And perhaps the Wikipedia INI page and a list of some key applications that use INI format could be added, eg:

  • MariaDB / MySQL
  • PHP
  • Systemd

Perhaps a whole page dedicated to .ini / .conf files with examples would make sense? :person_shrugging:

JMESPath

The community.general.json_query filter page could link to Selecting JSON data: JSON queries and that could link to the jp cli project and also the JMESPath Terminal project.

5 Likes

Hey @chris Thanks for the suggestions! We talked about this briefly at the docs working group today on Matrix. You can find the minutes here: Meeting Log | Ansible Docs | 2024-03-05 16:01:43

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!

2 Likes

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.

4 Likes

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

Thanks for chiming in @briantist it’s always nice to hear from you and see some examples!

@chris Thanks again for providing those suggestions. I’ve opened an issue in the docs repo here: Link "see also" sections as recommended in the forum · Issue #1200 · ansible/ansible-documentation · GitHub

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!

2 Likes