Extensions documentation (e.x.o) usability issues

Development
1

Hello,

I’ve noticed an admin user breaking his Administration application as a result of what I suspect to be an usability problem with our documentation on e.x.o. Basically, it seems like they have downloaded the xar from https://extensions.xwiki.org/xwiki/bin/view/Extension/Administration%20Application and imported it into their wiki, breaking page authors (XWiki.Admin does not exist) and making the application unusable. They did the same with Filter UI.

IMO, the current documentation pages are missing at least 2 things:

  1. Clear instructions on how to access the documented extension. Most of the time we jump straight to the features, but a user may not find out how to actually access the feature/application starting from the wiki’s homepage.
  2. Clearer highlighting of the fact that an extension is bundled with XS, i.e. not needing to manually download it unless they really know what they are doing. For this we could try:
  3. Adding a warning/info box at the beginning of the description, a bit like we do for deprecated extensions. The current Bundled With XWiki Standard field is not visible enough, IMO.
  4. Adding a confirmation dialog when pressing Download for extensions that are already bundled, reminding the user that they should not normally need to download it manually unless they know what they are doing.

Regular users also reach the org documentation, so maybe we should have well in mind that it might be read by absolute beginners and not only people already familiar with XWiki. We need some improvements to consider them as well, IMO.

For point 1, @vmassol reminded me of a previous discussion we’ve had around Extension Entry Points:

For point 2, @surli pointed out that one half of the solution would be to implement on the document import UI the same extension pages modification prevention features that we added when trying to edit a page. This should warn the user that they are about to perform a potentially breaking change.

Other ideas would be welcomed.

2

I’m actually wondering if we shouldn’t just hide a bit the download button: maybe I’m wrong but I feel that it’s now pretty rare that anyone need to actually download the extension. The need is generally to be able to install it from the Extension Manager.
On the same idea I think it was discussed at a point, but we’d need an “Install” button instead of “Download” that would allow to (for example) type an instance URL and would direct to the EM page of the extension for installing it directly in the instance.
We could even imagine having a dedicated xobject in XWiki.org users profiles to fill URLs of the instances they manage so that they could chose directly from this list of instances.

3

While I’m not against this idea, I would like to note that this list of instances will be public (as there is no way to hide objects on a page that is accessible in general) which might be unexpected for users, so we should make it clear that this list will be public (btw., I think having a protected document for private user preferences would be a good idea). Instead, it might be better to store the last (or a list of) instances in a cookie or local storage in the user’s browser.

Apart from that: +1 for making it more obvious that a certain feature is bundled and how to access that feature (regardless if it is bundled or not). While I think we shouldn’t remove the download button, I’m +1 for not making the download button the primary action on the page but instead provide better instructions (or help) with installing the extension.

1 Like