Major Description
The descriptions of the mention and useravatar macros, and of their parameters, repeat the macro names and use developer terms, so a user cannot tell what the macro adds, what to type in a field, or what an empty value does.
The macros to change, with the file where most of the fix is done:
- mention: defined in MentionsMacro.xml, descriptions in MentionsTranslations.xml.
- useravatar: defined in UserAvatarMacro.java, descriptions in ApplicationResources.properties.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| mention | D2 summary | "Insert a user mention." repeats the name "User Mention" behind the filler "Insert". It does not say that the macro writes a link to the user, shown as @ followed by their name, nor that the mentioned user gets a notification when the page is saved, which the documentation states. | |
| mention | C1 clarity | reference | The label "Reference" is a developer word for a field that picks a person, and the useravatar macro calls the same thing "Username". The description "The mentioned user or group reference." speaks of groups, which the picker does not offer: searching "Group" or "XWikiAdminGroup" lists nothing. |
| mention | C1 clarity | anchor | "The anchor to be used for linking to that mention (this anchor should be unique to the document as much as possible)." does not say what the anchor is for, what an empty value does, nor how to choose a unique one. The documentation suggests a random string from random.org. |
| mention | C1 clarity | type | "The type of the mentioned actor." does not give the values to type, user being the only one in XWiki Standard, nor the default. |
| useravatar | D2 summary | "Allows displaying the avatar for a specific user." mostly repeats the name "User Avatar", behind the filler "Allows displaying". It does not say that the picture comes from the user profile, nor that a default picture is shown when the user has none. | |
| useravatar | C1 clarity | height | "The image's height" does not give the unit, pixels, nor that an empty value keeps the height of the uploaded picture. The English name is the parameter ID "height", which the dialog shows capitalized. |
| useravatar | C1 clarity | width | "The image's width" does not give the unit, pixels, nor that an empty value keeps the width of the uploaded picture. The English name is the parameter ID "width", which the dialog shows capitalized. |
Impact found on macro fluidity
These 7 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D2 summary 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 of the macros and, for a name or a category, their definitions.