I know some UIs are also not displaying hint by default. The user have to hover a dedicated UI element (usually a small pill with a question mark), to see the hint.
It’s quite efficient in terms of used screen space use. I’m not sure regarding discoverability, usability, and accessibility.
I feel like the hints are much lighter and feel a lot more optional/easier to skip visually. Maybe we could also differentiate between a short hint and an optional, longer hint that would only be displayed when you click an additional icon?
Yes, that is similar to one of the ideas I listed above about displaying the first sentence only and then having an ellisis (...) or more link that can be clicked to see the full hint text.
If it’s done properly it can definitely be completely accessible. Using a standard UI for this would make it easier to keep high quality.
I think it could be useful in quite a few places, +1 from me to implement and use such a component instead of relying on dedicated UIs with various quality.
I agree with the problem but having a global solution to either hide/show or partially show them would hurt the usability too much IMO, especially for newcomers.
For me, the real problem is that some fields have their hints too large and specific. Take the “Root” field in the screenshot for example. After the first sentence the hint starts to explain very specific situations, that’s too much. It’s the same situation for the field “Page Hierarchy Mode”.
For these complete explanations the documentation is much more adequate. Each macro could have a link to the proper documentation somewhere (in the macro header for example). In the case of the Tree Macro it would be https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro.
The dificult part is that resolving this means going into each hint and rewrite it (we could publish some guidelines) while also making sure it’s full content is available on the extension documentation.
Note that not all hints are large like the ones pictured, on the admin page we have many hints that are short, concise and very helpful. The only change I would make to them is place the hint after the field so that the label and the input are closer together.
-1, the wiki must be self-contained (think, offline installation of XWiki in an enterprise context).
I tend to agree that some hint text are very verbose and could be shortened with a better writing style.
I would also split the topic in two:
For anything presented to simple users (i.e., not in advanced mode), the hint must be short. I feel like if we have the need for a longer explanation it means that the UI is not adapted to simple users and must be reworked.
For elements presented to advanced users, the need for longer explanations is understandable. In this case we could split the hint two. A first short sentence, always displayed. An option extra-hint for longer details, that would only be displayed though a user interaction (tbd, e.g., clicking a ‘more’ button or on hover in a popover).
I agree. I can’t think of a generic solution, we’ll need to fine-tune the hints incrementaly.
Most wiki macros actually ship with documentation as part of their macro page, which is linked in the macro index that can be reached from the help application. We could introduce a way for Java macros to also ship a documentation page. Then we could link to that documentation page in the wiki.
But what about just linking to the macro’s page in the wiki as in the macro index? Example on xwiki.org: macro index, nice example of chartjs providing a full documentation page. Note that this is not the documentation that is maintained on xwiki.org, this page is part of the extension and will be available in any wiki where the extension has been installed. So no stable URLs needed and no internet access.
Sounds like a start of a best practice that we could decide and document.
I think we could be a bit more precise. For example, add that for hints to simple users, the hint must not be more than 1 line (and the line less than N characters). Ofc we could also discuss exceptions but I feel it’s good to have a quantified best practice since that helps more the translator decide about the length and it would also allow us to automatically flag translations with too long characters, to review.
The difficulty of this best practice is that it would not be for us, the developers, but for the translators. So we’d need to make that rule/best practice visible to them in weblate. Not sure how.
But we could at least own the en_US translation and ensure they are short there.
I don’t know. On one hand I like the idea, OTOH it would need to not be the proper documentation. Right now we often show an example on the macro definition page, to show it works and how to use it but without any text (or very little). BTW if we were to make it part of help, we would need to translate the text to various languages.
My problem is that if we start considering these as doc, then we either need to make them complete or keep them simple but then link to the doc on xwiki.org, which raises the problem of URL stability, and also demarcation of documentation. And if we make the doc complete in macro def pages, then we shouldn’t duplicate that on xwiki.org too and then we don’t have a single place where everything is documented.
Just as a note, I think there’d need to be a lot of exceptions or very loose rules because of the difference of information density of various languages and the drastically different role a character plays in logograms and alphabets (such as the english one).
E.g. In a single line of chinese you can say so much more than a single line of english. I’m not sure it would make sense to enforce an arbitrary amount of characters or text-width.
I think this kind of thing is the interesting part of relying on human translators because they can assess unspoken things (such as “this is a short and straightforward english string” or “this is an in-depth hint that uses only common words”) and retranscribe them appropriately in the context of their language.
But in the end this is more of a matter of preference from the translation contributors, it’d be great to get feedback from them. Should I open a discussion on the translation category of this forum?
It feels more a matter of UX for users than translators or devs. You could argue that most of our translators are also users.
For me we’re not yet fully ready for a discussion since we haven’t discussed how we could convey best practices to translators inside weblate (except in a dashboard panel, but that’s probably not enough). Are there features in weblate where we could provide custom validators and display a warning when there are more than N characters for ex (asking to verify that it’s not too long, and point to a link explaining the best practice on xwiki.org)?
Now, you could start a discussion sure, it doesn’t hurt
To come back on the original topic I do believe we should hide the hints by default and only display them following a user interaction (click on a dedicated button the famous pill with question mark for example).
My rationale is that either the field is self explanatory by its title, or the user already know it and you just don’t need the hint. Or in the contrary, the field is ambiguous and the user doesn’t know its purpose and then they need guidance: in this case, the guidance might be detailed so that the user understand properly the implication for using that field, hence the long hints.
So for me it’s really not a problem of having long hints and I really think we should improve them for having more detailed explanation wherever needed in the wiki. But indeed by default they should be hidden.
This makes sense for UIs that are used often. But I imagine that you don’t access the wiki administration sections daily for instance. Even if you have seen them once, you probably still want to view the hints, especially for areas where the configuration options can mess the entire wiki.
+1 for this
-0 for this. Displaying many question mark icons will be distracting, and having to click on each of them to see the hints, at least the first time you access the form, is annoying for me.
-0 for this. If we chose to display a hint, it should be between the label and the field:
screen readers should read the hint before announcing the field; we can make hacks to keep the hint before the field in the DOM and display it afterwards with CSS, but I don’t think it’s a good idea
when navigating the form using the keyboard and the page has vertical scrollbar you can end up focusing the input at the bottom of the page with its hint remaining hidden.
The length of a line depends where text is displayed and also on the screen width / resolution. I do agree we should keep hints short though.
One thing that has not been mentioned is that IMO we should use hints only if they bring additional value / explanation compared to the label. My feeling is that we often add a hint just to have one (i.e. to be consistent) and the hint is simply redundant with the label. To give some examples:
Title
Title of the new page
Default Language
Select the default language of the wiki
Annotations are activated
Decide if annotations are active on the wiki
So for me the solution is:
remove hints that don’t bring any value, or rephrase them to bring some value if there’s a need for that (i.e. the label is not self-explanatory)
make sure labels and hints are visually distinct, i.e. styled differently (should be already the case normally)
rephrase long hints if possible to be more concise
show only the first line of the hint and provide a more / ellipsis action to see the entire hint
If there should be a decision where more info is provided hidden in any way I wouldn’t do it with a hover or mouse over. This is in many ways often inaccessible. Hovering has to be done with a mouse. Mobile devices don’t have a mouse and can’t show hovers. Using a desktop pc but with keyboard only can’t show you infos only accessible by mouse hovering.
