|
|
| |
| |
| |
|
| Summary: |
Improve the descriptions of the notifications macros and of their parameters |
| Issue Type: |
 Improvement |
| Affects Versions: |
17.10.14, 18.8.0 |
| Assignee: |
Unassigned |
| Components: |
Notifications |
| Created: |
22/Oct/26 11:27 |
| Priority: |
 Major |
| Reporter: |
Charpentier Lucas |
| Description: |
The names and descriptions of the notifications and activity macros, and of their 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. Several are also wrong for some uses of the macro. The same problems repeat across the macros:
- The descriptions of the preferences macros say "the preferences of the current user", which is wrong when the target is the wiki or when an administrator gives another user, and never say what the macro shows: a table with switches, a list or a form, saved right away.
- The user parameter of the six preferences macros speaks of "user reference" and "context user", and the sentence about the administration right is hard to follow.
- 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.
KOs covered
| Macro |
Criterion |
Parameter |
Problem |
| activity |
C1 clarity |
authors |
Does not give the format of an author, like XWiki.Admin. |
| activity |
C1 clarity |
entries |
Does not say that it is the maximum number of events listed, and the notifications macro calls the same value "count". |
| activity |
C1 clarity |
spaces |
Uses "spaces", a term the UI no longer shows, and "local serialized references", a developer wording, with no example like Sandbox. |
| activity |
C1 clarity |
wikis |
Does not say whether a wiki is given by its name or its identifier, nor that only the events of these wikis are listed. |
| activity |
D2 summary |
|
Says how the macro is built, for backward compatibility with Activity Stream, not that it lists the recent events of the wiki. The French and German descriptions do say it. |
| 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. |
| notificationsApplicationsPreferences |
C1 clarity |
user |
Uses "user reference" and "context user" instead of saying that an empty field means the user viewing the page, shows the wiki syntax around "user" as is, refers to the target parameter by its identifier, and the sentence about the administration right is hard to follow. |
| notificationsApplicationsPreferences |
D2 summary |
|
Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a table of applications with a switch for the notifications menu and one for the emails, saved right away. |
| notificationsAutoWatchPreferences |
C1 clarity |
user |
Same as for notificationsApplicationsPreferences. The French and German descriptions are the English text. |
| notificationsAutoWatchPreferences |
D2 summary |
|
Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a single list to choose when a page is watched after an edit, saved right away. |
| notificationsCustomFiltersPreferences |
C1 clarity |
user |
Uses "user reference" and "context user" instead of saying that an empty field means the user viewing the page, and the sentence about the administration right is hard to follow. |
| notificationsCustomFiltersPreferences |
D2 summary |
|
Repeats the name, is wrong when the target is the wiki or when no user is given, and does not say that the result is a table where filters are added, enabled, disabled and deleted, nor what a custom filter is. |
| notificationsEmailPreferences |
C1 clarity |
target |
Has no description: the dialog does not say what a target is, nor that it accepts "user" and "wiki", the latter needing the administration right. |
| notificationsEmailPreferences |
C1 clarity |
user |
Same as for notificationsApplicationsPreferences. |
| notificationsEmailPreferences |
D2 summary |
|
Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a form with two lists, the email frequency and the level of detail, saved right away. |
| notificationsFiltersPreferences |
C1 clarity |
user |
Same as for notificationsCustomFiltersPreferences. |
| notificationsFiltersPreferences |
D2 summary |
|
Repeats the name and is wrong for another user. The deprecation sentence gives no link and does not say that the two replacements split the table into system filters and custom filters. |
| notificationsSystemFiltersPreferences |
C1 clarity |
user |
Same as for notificationsCustomFiltersPreferences, and does not say that the field is ignored when the target is the wiki. |
| notificationsSystemFiltersPreferences |
D2 summary |
|
Repeats the name, is wrong when the target is the wiki, and does not say that the result is a table of the 6 system filters with a switch for the alerts and one for the emails, saved right away. The French and German descriptions are the English text. |
Impact found on macro fluidity These 27 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. |
|
|
|
|
|
| |
| |
|
| Description: |
The names and descriptions of the notifications and activity macros, and of their 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. Several Some are also wrong for some uses of the macro .
The same problems repeat across the macros :
* The descriptions of to change, with the preferences macros say " page that defines each one and the preferences file where most of the current user", which fix is wrong when the target is the wiki or when an administrator gives another user done:
* activity: defined in [ActivityMacro.xml|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-legacy/xwiki-platform-legacy-notifications/xwiki-platform-legacy-notification-activitymacro/src/main/resources/XWiki/Notifications/Code/Legacy/ActivityMacro.xml] , and never say what descriptions in the macro shows [Translations.xml|https : a table with switches, a list or a form, saved right away //github . com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-legacy/xwiki-platform-legacy-notifications/xwiki-platform-legacy-notification-activitymacro/src/main/resources/XWiki/Notifications/Code/Legacy/Translations.xml] of the legacy activity macro module.
* The {{user}} parameter of notifications: defined in [NotificationsMacro.xml|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-macro/xwiki-platform-notifications-macro-ui/src/main/resources/XWiki/Notifications/Code/Macro/NotificationsMacro.xml], descriptions in the six preferences macros speaks [Translations.xml|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-macro/xwiki-platform-notifications-macro-ui/src/main/resources/XWiki/Notifications/Code/Macro/Translations.xml] of "user reference" and "context user", and the sentence about the administration right is hard to follow 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 six notifications preferences macros are left out: 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.
h2. KOs covered
||Macro||Criterion||Parameter||Problem||
|[activity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/activity/]|C1 clarity|{{authors}}|Does not give the format of an author, like {{XWiki.Admin}}.|
|[activity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/activity/]|C1 clarity|{{entries}}|Does not say that it is the maximum number of events listed, and the notifications macro calls the same value "count".|
|[activity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/activity/]|C1 clarity|{{spaces}}|Uses "spaces", a term the UI no longer shows, and "local serialized references", a developer wording, with no example like {{Sandbox}}.|
|[activity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/activity/]|C1 clarity|{{wikis}}|Does not say whether a wiki is given by its name or its identifier, nor that only the events of these wikis are listed.|
|[activity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/activity/]|D2 summary| |Says how the macro is built, for backward compatibility with Activity Stream, not that it lists the recent events of the wiki. The French and German descriptions do say it.|
|[notifications|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/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.|
|[notificationsApplicationsPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsApplicationsPreferences/]|C1 clarity|{{user}}|Uses "user reference" and "context user" instead of saying that an empty field means the user viewing the page, shows the wiki syntax around "user" as is, refers to the target parameter by its identifier, and the sentence about the administration right is hard to follow.|
|[notificationsApplicationsPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsApplicationsPreferences/]|D2 summary| |Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a table of applications with a switch for the notifications menu and one for the emails, saved right away.|
|[notificationsAutoWatchPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsAutoWatchPreferences/]|C1 clarity|{{user}}|Same as for notificationsApplicationsPreferences. The French and German descriptions are the English text.|
|[notificationsAutoWatchPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsAutoWatchPreferences/]|D2 summary| |Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a single list to choose when a page is watched after an edit, saved right away.|
|[notificationsCustomFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsCustomFiltersPreferences/]|C1 clarity|{{user}}|Uses "user reference" and "context user" instead of saying that an empty field means the user viewing the page, and the sentence about the administration right is hard to follow.|
|[notificationsCustomFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsCustomFiltersPreferences/]|D2 summary| |Repeats the name, is wrong when the target is the wiki or when no user is given, and does not say that the result is a table where filters are added, enabled, disabled and deleted, nor what a custom filter is.|
|[notificationsEmailPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsEmailPreferences/]|C1 clarity|{{target}}|Has no description: the dialog does not say what a target is, nor that it accepts "user" and "wiki", the latter needing the administration right.|
|[notificationsEmailPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsEmailPreferences/]|C1 clarity|{{user}}|Same as for notificationsApplicationsPreferences.|
|[notificationsEmailPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsEmailPreferences/]|D2 summary| |Repeats the name, is wrong when the target is the wiki or another user, and does not say that the result is a form with two lists, the email frequency and the level of detail, saved right away.|
|[notificationsFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsFiltersPreferences/]|C1 clarity|{{user}}|Same as for notificationsCustomFiltersPreferences.|
|[notificationsFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsFiltersPreferences/]|D2 summary| |Repeats the name and is wrong for another user. The deprecation sentence gives no link and does not say that the two replacements split the table into system filters and custom filters.|
|[notificationsSystemFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsSystemFiltersPreferences/]|C1 clarity|{{user}}|Same as for notificationsCustomFiltersPreferences, and does not say that the field is ignored when the target is the wiki.|
|[notificationsSystemFiltersPreferences|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/notificationsSystemFiltersPreferences/]|D2 summary| |Repeats the name, is wrong when the target is the wiki, and does not say that the result is a table of the 6 system filters with a switch for the alerts and one for the emails, saved right away. The French and German descriptions are the English text.|
h2. Impact found on macro fluidity
These 27 14 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C1 clarity, D2 summary and D3 category of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. 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. |
|
|
|
|
