Improve Visibility of the "Extension" Link in Documentation

Development
,
1

Hello, everyone! :waving_hand:

This proposal is about improving the visibility of the “Extension” link used in /documentation pages.

Context: The new documentation guidelines and process using the documentation application are being implemented in /documentation. While applying these changes, some feedback was received regarding the “Extension” link that redirects to the corresponding page on Extensions. More specifically: the badge described here.

The main points raised were that the link being placed in the badge is:

  • not very visible
  • not very intuitive as a clickable element
  • confusing because it looks like a tag/pill

This styling mixes the keyword/ tag UX pattern with something that is actually a navigation link to extra information.

Problem: Currently, the “Extension” link is displayed together with the Type and Target as badges. However, this elements have a different purpose, they are clickable metadata keywords, while the “Extension” is a link to further reading.

On the Extensions page, users can find technical information about the extension, including the available support (if any). (See Improve information about the level of support of extensions - #36 by tkrieck)

Because the “Extension” link is not clearly identifiable as navigation, users reading documentation from /documentation may not easily discover this additional information.

Proposed improvements:

1. Update the link label and styling

Change the label from “Extension” to “Extension details ➝”. This would indicate that it’s a link that redirects to another wiki, the arrow also helps to convey the idea of navigation.

2. Separate the extension link from the metadata badges

Currently all the three badges are grouped together in the content footer.

Option 1:

Move on the left side: Type+ Target and keep on the right side just the “Extension details ➝” link.

Option 2:

Keep on the content footer the Target+ Type badges and move “Extension details ➝” in the after content header. (Or vice versa).

Another idea: Also a possible solution would be to decide whether the right location for the available support information should remain on the extension-wiki, or if it should be moved directly to the main wiki on documentation pages on /documentation. If you think it’s a relevant option, it could be discussed separately, in another thread.

WYT about this approach? Other suggestions to improve the visibility of the extension information are very welcome. Please feel free to share also other possibilities of approaching this.

Thank you!

2

Hi @tkrieck, your input on this would be very valuable. Thank you!

1 Like
3

So:

  • “Not very visible”: yes and that was done on purpose. We definitely don’t want it to be very visible as it’s not information useful to users (only to admins and only in some specific cases)
  • “not very intuitive as a clickable element”. Ok but it’s not different from the other pills for the type and target so we need to improve all of them consistently.
  • “confusing because it looks like a tag/pill”. It’s meant to look like a tag/pill or a button. I’m not sure why or what is confusing. A button is clickable and has the same L&F.
  • “This styling mixes the keyword/ tag UX pattern with something that is actually a navigation link to extra information.”. All tags are also navigation links so I don’t understand this point.

I don’t agree about it since it doesn’t solve the issue for the other 2 badges which are also clickable. I’d prefer something like displaying the link underscored on mouse hover for ex. To be checked with @CharpentierLucas and/or @tkrieck for what’s best.

I don’t like this one too much since it makes it way too visible IMO.

You also need to remember that:

  1. the info is needed only for admins (and only a subset of admins).
  2. the info is needed only for extensions and not for XS (since users don’t need to install bundled XS extensions or even know that they are extensions).

OTOH what could work would be to do this but only for Extensions doc (and not XS).

Option 3:

Another idea is to change the Documentation Sheet so that it adds automatically an “Extension” section for Extensions Admins docs, with some predefined text saying that the doc page refers to features found in an Extension (link) and that readers can check there how to install it and its support level.

For ex, it would appear on https://www.xwiki.org/xwiki/bin/view/documentation/extensions/admin/s3-blob-store/ and on https://www.xwiki.org/xwiki/bin/view/documentation/extensions/admin/s3-blob-store/configure-s3/

Option 4:

Do the same as option 3 but:

I don’t like 4 too much because it’s manual and because it’s not as precise as option 3 (which points to exactly the extension being concerned and the extension project).

Note that options 1 is compatible.

I don’t currently have a strong opinion between option 2 (limited to Extension docs) and option 3. Option 3 (limited to Extensions Admin docs). Note that option 3 would force us to have admin top level pages for all extensions, but that could be a good thing, even if it would feel to add a bit of duplication with exo. So I have a small preference for option 2 if done in a not too visible way.

Note that I’d still keep the Extension badge in the footer for non-extension docs or for non-admin-extensions docs.

Thanks

4

I understand some of the confusion on the badge but not because of the mentioned characteristics. As @vmassol pointed out they are, in fact, intentional.

Now, while all of the tag/pills are indeed clicable and open diferent links, only one of them doesn’t opens a filtered list, pointing to the extension page itself, so some of the confusion might happen because of this.

We could change the link to present a filtered list of extensions (so basically documentation/extensions) and use Option 3 that Vincent proposed to make the extension info extra clear at the beggining of the doc and also point to the correct extension page.

Thanks