|
| Summary: |
Improve the descriptions of the notifications macros macro and of their its parameters |
| Description: |
The descriptions of the notifications and activity macros macro , and of their 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 macros to change, with the page that defines each one and the file where most of the fix macro is 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], descriptions in the [Translations.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/Translations.xml] of the legacy activity macro module.
* 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 [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 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.
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.|
h2. Impact found on macro fluidity
These 14 9 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. |
|
