|
| Summary: |
Improve the names and descriptions of the code, container, gallery and menu macros and of their parameters |
| Issue Type: |
 Improvement |
| Affects Versions: |
17.10.14, 18.8.0 |
| Assignee: |
Unassigned |
| Components: |
Menu, Rendering - Code Macro, Rendering - Container Macro, Rendering - Gallery Macro |
| Created: |
22/Oct/26 11:58 |
| Priority: |
 Major |
| Reporter: |
Charpentier Lucas |
| Description: |
The names and descriptions of the code, container, gallery and menu macros, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Several use developer terms, are copied from another macro, or miss the values to type. The macros to change, with the file where most of the fix is done:
The main problems:
- The name and description of container are developer terms for what users know as columns, and rely on wiki syntax groups that the WYSIWYG editor cannot create.
- The image and title parameters of code call the code block a message box, a description copied from the Box macro.
- The width, height and class parameters of gallery give no unit or example, and are not translated.
- The type and label parameters of menu do not list the accepted values or say that the label is only read by screen readers.
- code is only in the Formatting category, while users may look for it under Development.
KOs covered
| Macro |
Criterion |
Parameters |
Problem |
| code |
D3 category |
|
Only in Formatting, like box, while a user may look for code under Development, where html is. A macro can have several categories since XWiki 14.6, so code could also be in Development. |
| code |
C1 clarity |
image |
The description "the image which is to be displayed in the message box" calls the code block a message box, and does not say what value is expected, an attachment or a URL. |
| code |
C1 clarity |
title |
The description "the title which is to be displayed in the message box" calls the code block a message box. It does not say either that the title accepts wiki syntax. |
| container |
D1 wording |
|
"Container" is a developer term for what the documentation shows users as columns: its only usable example is {{container layoutStyle="columns"}}, the other one, "grid", being a layout that a developer has to implement. |
| container |
D2 summary |
|
The description "A macro to enclose multiple groups and add decoration, such as layout." does not say what the macro adds to the page, columns, the only layout available: "groups" is a wiki syntax term and "decoration" is vague. |
| container |
C1 clarity |
$content |
The description "The content to enclose in this container (wiki syntax). For the "columns" layout, a group should be added for each column." relies on the wiki syntax term "group", (((...))), which a WYSIWYG user does not know and cannot insert. |
| container |
C1 clarity |
justify |
The English name is the ID, "justify", and the description "Flag specifying whether the content in this container is justified or not." uses the technical term "flag" and does not say that it only has an effect with the columns layout: {{container justify="true"}}Text{{/container}} is not justified. |
| container |
C1 clarity |
layoutStyle |
The description "The identifier of the container layout (e.g. "columns")." uses the technical term "identifier" and does not list the accepted values nor say what the columns layout does, one column per group. Without it the macro renders its content as is. |
| gallery |
C1 clarity |
$content |
The description asks for images "specified using the syntax of the current page", with an example for "XWiki 2.0 syntax": technical terms, and an outdated syntax version. It does not say that anything other than images, like text or a list, is dropped. |
| gallery |
C1 clarity |
class |
The name is the parameter ID, "Class", in every language, and French and German show the English description "Custom CSS class names to set on the gallery container". |
| gallery |
C1 clarity |
height |
The description "The gallery height" repeats the name and does not say what value is expected, a CSS length like 349px, nor that an empty value keeps the default height of 349px. The name is the parameter ID in every language, and French and German show the English description. |
| gallery |
C1 clarity |
width |
The description "The gallery width" repeats the name and does not say what value is expected, a CSS length like 620px or 100%, nor that an empty value keeps the default width of 620px. The name is the parameter ID in every language, and French and German show the English description. |
| menu |
C1 clarity |
type |
The description "The optional menu type determines the menu appearance and behaviour. The supported values are: horizontal (default value) and vertical." does not mention the modifiers fixedWidth, collapsible and open, which the most common example of the documentation sets, type="horizontal fixedWidth", nor that they are combined with spaces. |
| menu |
C1 clarity |
label |
The description "Optional menu label used to describe the content of the menu. Especially important for assistive technologies and accessibility of the menu." does not say that the label is not displayed, only announced by screen readers, while the name "Label" suggests a visible title of the menu. |
Impact found on macro fluidity These 14 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D1 wording, D2 summary, 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 of the macros and, for a name or a category, their definitions. |
|
