Documentation: mention the plugin type more prominently

[felixfontein]

Summary

A common issue with the documentation (docs.ansible.com/ansible/latest/) is that the plugin type is not mentioned very prominently in various situations (see for example ansible/ansible#75652). If you look at https://docs.ansible.com/ansible/latest/collections/ansible/builtin/ and search (with Ctrl+F) for file or debug, you will find two plugins each (each one module and a lookup resp. strategy plugin). Or if you use the site search (search for ansible.builtin.file), you need to look a bit more closely than necessary to figure out which of the two is the module and which is the lookup.

I've started ansible-community/antsibull#364 to improve this situation, but right now basically all changes are somewhat controversial. In this issue I'd like to figure out which changes would have a large support and could be put into a less controversial PR, so it can be merged and some improvements can go live.

In the following I will go through the changes and give pros and cons for each of them. If someone mentions another good argument for or against one of these, I will edit this post and add them. If you want to give your support for a change, you can write 1+ (give support to change 1) or 2- (say you don't like change 2).

1. Page title (both the top-level title visible on the page, and in the HTML <title> tag). This is also what's shown in the first line of the page search results.

   • Pros of having the plugin type in the title (https://ansible.fontein.de/collections/ansible/builtin/file_module.html):
     • The plugin type shows up more prominently in the search results;
     • When looking at the plugin/module page, you can directly see in the title what the plugin type is;
   • Cons of having the plugin type in the title (https://docs.ansible.com/ansible/latest/collections/ansible/builtin/file_module.html):
     • More text between the plugin name and the short description, which is more to parse and it needs more horizontal space (resp. vertical space due to line breaks);

2. See alsos of type "module": mention module.

   • Pros of having the plugin type in the seealso entry (https://ansible.fontein.de/collections/ansible/builtin/file_module.html#see-also):
     • It is more clear that this FQCN belongs to a module, and not to some other kind of plugin (for something even better, see 'Alternatives' below);
     • It will also say "module" if the documentation author provided an explicit description which does not mention that this FQCN belongs to a module;
   • Cons of having the plugin type in the seealso entry (https://docs.ansible.com/ansible/latest/collections/ansible/builtin/file_module.html#see-also)
     • The fact that this is a module is already mentioned in the description. (Assuming the documenation author didn't provide one explicitly that does not mention this!)
   • Alternatives:
     • Include the plugin type in the link title: this changes the color, but on the other hand is better for screen readers (since the title is more descriptive: you really know what the link refers to, since only combintation of FQCN and plugin type is unique, and not just parts of what the link refers to)

3. Plugin index (for a collection): mention the plugin type next to the FQCN

   • Pros of having the plugin type in every plugin entry (https://ansible.fontein.de/collections/ansible/builtin/#lookup-plugins):
     • It makes the link title more useful for screen readers;
     • If you have a long list of plugins of this type, you might not see the title of the list and thus you don't know whether you are in the modules list, the lookup list, or somewhere else;
     • User can search the page for "file look" (with Ctrl+F) to directly find the file lookup;
   • Cons of having the plugin type in every plugin entry (https://docs.ansible.com/ansible/latest/collections/ansible/builtin/#lookup-plugins)
     • The list has a title which says which type of plugins/modules this is; repeating that information in every line is visual clutter;
   • Alternatives:
     • Move the plugin type outside of the link title, so it is visually separated. The disadvantage of this is that it makes the link title less expressive (which is bad for screen readers).
       • It would be better to use formatting, like make the FQCN bold and the plugin type not; unfortunately RST does not allow nested formatting :(

Personally I think that for 1, the advantages definitely outweight the disadvantages. For 2 and 3 it is definitely debatable though. I'd already be totally happy if a subset of this PR with 1 but not 2 and 3 gets wide support so it can be merged.

[felixfontein]

As an example of how to vote on this, I'm voting:

1+
2+ (Alternatives: I would even move the plugin type in the link title)
3+ (Alternatives: I would keep the plugin type in the link title)

[briantist]

I originally brought up the "visual clutter" issue about 3, but I do want to be clear that I don't find it so egregious as to support removing an option that would be better for accessibility, so I'd rather have the slight clutter to better support screen reader users.

Is it possible for us to set aria-label (or an appropriate ARIA attribute) on the link as way of us having our cake and eating it too?

Also of note, I'm not very familiar at all with web accessibility solutions and their pros/cons/quirks. This might be a good topic for the diversity working group.

[felixfontein]

@briantist I think for aria-label we'd have to use .. raw:: html, or some self-created role or some Sphinx plugin which already implements this somehow. I'm not aware how to do this with plain RST/Sphinx. (A more specific link on this topic: https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA8.html)

[tadeboro]

I am 1+ and 3+ since additional clutter in those use cases is minimal and the benefits outweigh the cons IMHO. I am not too sure about 2 since the type of linked think is repeated in the next line (assuming we go with option 1).

So my vote would be:

1+ (having info in the title is awesome)
3+ (makes things "<c-f> file look" possible)
2- (assuming we go with 1)
2+ (if we do not go with 1)

[rockaut]

I second that. Please also consider httpapi plugins there too if not already thought about it.

[acozine]

I feel that the pros outweigh the cons overall.
1+ definitely
3+ definitely
2+ but this one I'm willing to let go - I think most See Also references are to modules, and the descriptions mention module already, so I think these references are less confusing and less likely to lead users to the wrong pages

[samccann]

1+
3+
2 (don't really have an opinion.)

[felixfontein]

Thanks for all your feedback! I removed the extra module mentioning from the PR; I think with this change everyone who spoke out here will be happy. We can work on seealso again in another PR; I think it is more important to get the other changes out first.

[felixfontein]

I created #61 to vote on this PR.