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:
- 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.
- 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:
- Adding a warning/info box at the beginning of the description, a bit like we do for deprecated extensions. The current
Bundled With XWiki Standardfield is not visible enough, IMO.
- 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:
- [xwiki-devs] [Proposal] Entry point for Extensions - Vincent Massol - org.xwiki.devs - MarkMail
Extension Entry Points (Proposal.ExtensionEntryPoints) - XWiki
This would fit quite well on both the XWiki UI side (ability to open an extension once you’ve installed it) but also on the e.x.o documentation side, extracting this metadata from the pom.xml and presenting it in the extension documentation page.
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.