Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
17.10.14, 18.8.0
-
None
-
Unknown
-
Description
The 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. Some are also wrong.
The macros to change, with the page that defines each one and the file where most of the fix is done:
- activity: defined in ActivityMacro.xml, descriptions in the Translations.xml of the legacy activity macro module.
- notifications: 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 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.
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. |
Impact found on macro fluidity
These 14 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
-