Based on this Jira from @CharpentierLucas, I’ve been looking into the help resources we currently offer to our users and how they are presented. I realize that this will be really a two-on-one proposal, I chose to keep them into one proposal because they are highly related, and the discussion should help both. But let me know if it would be best to keep them separated on the proposals page.
We have documentation available online at https://www.xwiki.org/xwiki/bin/view/Documentation/, and by default, this is linked in the right sidebar panels of a new wiki. While this setup works well for the initial out-of-the-box experience, the documentation can become difficult to find on established wikis with new users, especially if Admins forget to link these resources elsewhere.
Proposal 1.1: A Centralized Help Section
To improve visibility and accessibility, I propose creating a single access point for all help-related materials. This would provide a centralized location to make documentation easily visible without interfering much with current wiki customizations.
I suggest placing this section in one of two locations:
A - A Discrete Button on the Header
Pros: Highly visible and in a location typically reserved for help in other applications.
I would love to hear your thoughts on these options or any other suggestions you might have.
Proposal 1.2: Access to Keyboard Shortcuts
Regarding the specific need mentioned in the Jira, I believe it is important to keep a page of XWiki keyboard shortcuts easily accessible without taking the user out of their current context. To achieve this, I propose displaying the shortcut document as a modal dialog rather than a default page. This would allow users to quickly consult the shortcuts and then close the dialog without losing their place.
Proposed Implementation:
The modal dialog should contain an introductory text pointing to the full user documentation, opening in a new tab.
The search functionality would be a simple, real-time JavaScript filter, like the one on this page.
The “command - shortcut” order would be inverted compared to the user guide, following the user logic: “I want to do something; what is the shortcut?”
The only available action in the dialog, aside from searching, would be closing this dialog.
There’s an extension point here so I doubt things would get too bad Most customization should take into account the fact that we can add another button/dropdown here
I doubt the drawer will ever get deprecated. Even if it was, this section would be the least of our concerns when deprecating the drawer.
In my opinion option A makes more sense since it’s mostly for new users. Option B is quite difficult to find, it’d probably be easier to just search for the help page directly in Quick search for most users. IMO the drawer should contain more technical parts of the UI (e.g. the various indexes make sense here because they are used mostly by advanced users).
Proposal 1.2: Access to Keyboard Shortcuts
I agree with the overall idea. Should we add the CKEditor shortcuts when we’re in WYSIWYG edition?
Should the filter work on the command description or the shortcut key (or both)? Maybe we could also add a toggle to search in descriptions and keys?
In the hint at the top of the modal, I think it’d make sense to add a link towards the section containing the current user preferences for keyboard shortcuts (once it’s merged ofc).
I believe we should, as it is an integral part of using XWiki.
Ideally both, but perhaps we should have a way of searching only on keys or only on descriptions. I don’t see a need to search on both at the same time. Perhaps we could use a select box before the text input with “Command” and “Keys” as options.
I think we should include them all the time, not just when you are in edit mode.
On the contrary, I don’t really see the need to search only in one of them. I think we should keep it simple and search in both at the same time, keeping only the search text box.
Since it’s only for new users (and they represent maybe 1% or less of our users), it shouldn’t take a highly visible spot that bloats the main UI. It needs to be available but discrete. If someone looks for it, it should be findable but not put in your face every time you look at the screen!
Thus, the location in the drawer is a better place IMO.
So for me it’s 1.1 B
Regarding proposal 1.2 I agree with what was proposed. It’s missing an explanation of how it gets triggered (it needs some keyboard shortcut IMO + some location where the user can learn about, most likely somewhere in the help app).
BTW it would be good that we agree, once and for all about the general rule, which for me is:
The more visible is a button or text, the more useful it is for accomplishing daily tasks. In other words: more visibility = more usage
We don’t put stuff in more permanent visible place for discoverability!
In some cases, it’s ok to have stuff very visible for discoverability but it then needs to be removed once seen, or discardable. This is the case for example for the Tour.
It’s a section of the help section from proposal 1.1. the last one is called “Keyboard Shortcuts”. So it would be accessed by a menu item, but a keyboard shortcut would be of great help too for a quick check.
Just as a note, the higher visibility would help mostly new users inside established wikis, so not necessarily on new deployments of XWiki. More experienced users could use it as a reminder of features or as a refresher on less used features, but for this the drawer implementation would be usable enough.
Looks good to me in general. But I wouldn’t take a hard line on the second item because we can have features in the future that needs to be visible (by usefulness or importance). So rephrasing it a bit would be like “We don’t put stuff in more permanent visible placejustfor discoverability.” So it kind of reinforce the first rule. WDYT?
Most customization should take into account the fact that we can add another button/dropdown here