Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
15.4.5
-
None
-
Unknown
-
Description
The descriptions of the figure and figureCaption macros, and of their content, use jargon or repeat the names, and do not say how the two macros work together. Both macros are in the Development category, while a user looking for a captioned image or table looks in Layout or Content.
The macros to change, with the file where most of the fix is done:
- figure: defined in FigureMacro.java, descriptions in ApplicationResources.properties.
- figureCaption: defined in FigureCaptionMacro.java, descriptions in the same ApplicationResources.properties.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| figure | D2 summary | The description "Tag content as an illustration and with an optional caption." uses the jargon "Tag", is not grammatical, and does not say that the macro shows the content as a figure, with a caption below it. | |
| figure | D3 category | The macro is in the Development category, while gallery is in Layout and box in Formatting. A user looking for a way to add a captioned image or table would look in Layout or Content, not Development. | |
| figure | C1 clarity | $content | The description "Illustration(s) and caption" does not say that the caption is added with the Figure Caption macro. |
| figure | C1 clarity | type | The description does not say what the type changes, for example the numbering by the Numbered Figures Application or the inline style, and its second sentence is not grammatical: When the type "automatic", the actual type will be defined based on the macro content. |
| figureCaption | D2 summary | "Provide a figure caption when used inside the Figure macro." repeats the name and only adds where the macro goes. It does not say where the caption is shown, below or above the content of the figure, nor that it must be the first or last element of the figure. | |
| figureCaption | D3 category | The macro is in the Development category, like figure, while a user looking for a way to caption an image or a table would look in Layout or Content, as noted for figure. | |
| figureCaption | C1 clarity | $content | The description "Caption content" only repeats the name of the parameter. It does not say that the content is shown as the caption of the figure, nor that it accepts wiki syntax and blocks like lists and tables. |
Impact found on macro fluidity
These 7 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, 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.