Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
17.10.14, 18.8.0
-
None
-
Unknown
-
Description
The descriptions of the notifications macro, and of its parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Many of them repeat the macro name, describe how the macro is built, or use developer terms, so a user cannot tell what the macro adds to the page or what to type in a field. Some are also wrong.
The macro is defined in NotificationsMacro.xml, descriptions in the Translations.xml of the notifications macro module.
The same problems repeat across the parameters:
- The filter parameters of the notifications macro refer to useUserPreferences by its identifier instead of its label, say "to consider" instead of saying that only the matching events are shown, and give no example of the expected value.
The activity macro is left out: it is a legacy macro, to be deprecated in XWIKI-25515. The six notifications preferences macros are left out too: they are only meant for the notification preferences and administration UI, and should be hidden from the macro lists with the Internal category, see XWIKI-21063.
KOs covered
| Macro | Criterion | Parameter | Problem |
|---|---|---|---|
| notifications | C1 clarity | displayReadStatus | The sentence is garbled, and does not say that the status is also the control to mark an event as read. |
| notifications | C1 clarity | displayWatchedUsersOnly | Wrong: it says that the Users field is used when it is filled, while the macro always uses the people the reader follows, and only shows "You are not following anybody." when there are none. |
| notifications | C1 clarity | pages | Gives no example of a full reference, refers to useUserPreferences by its identifier instead of its label, and "to consider" does not say that only the events of these pages are shown. |
| notifications | C1 clarity | spaces | Uses "space", a term the UI no longer shows, refers to useUserPreferences by its identifier, and does not say that only the events of these locations and their child pages are shown. |
| notifications | C1 clarity | tags | Refers to useUserPreferences by its identifier, and does not say that only the events of the pages carrying these tags are shown. |
| notifications | C1 clarity | users | Does not give the format of a user, like XWiki.Admin, refers to useUserPreferences by its identifier, and does not say that only the events of these users are shown. |
| notifications | C1 clarity | wikis | Refers to useUserPreferences by its identifier, does not say that only the events of these wikis are shown, nor whether a wiki is given by its name or its identifier. |
| notifications | D2 summary | Repeats the name, is not grammatical, and does not say that the macro shows the recent changes of the wiki, with a "Load older notifications" button, a mark as read control on each event and an RSS link. | |
| notifications | D3 category | Only in the Notifications category, next to the settings macros meant for the administration. A user looking for a list of recent changes also looks in Content, where documents and liveData are. |
Impact found on macro fluidity
These 9 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D2 summary and D3 category of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations and, for the category, the macro descriptors.
Attachments
Issue Links
- is related to
-
-
- Open
-
- relates to
-
-
- Closed
-