Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
2.4.1
-
None
-
None
-
Unknown
-
Description
The descriptions of the content and parameters of the PlantUML macro do not say what to type, what each value is for, or what an empty value does, so a user who does not know PlantUML finds no help in the dialog.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| plantuml | C1 clarity | $content | "The textual definition of the diagram" does not say what to type: the PlantUML language, which the macro wraps in @startuml and @enduml when the content does not start with that tag, or the other supported languages. A user who does not know PlantUML finds nothing in the dialog, nor a link to its language reference. |
| plantuml | C1 clarity | format | "the PlantUML diagram output format" does not say what each value is for, which the documentation does, svg scaling better and carrying links, and it does not say what the blank option stands for, see C3. |
| plantuml | C1 clarity | server | "the PlantUML Server URL" does not say that an empty value uses the server configured for the wiki, nor that its domain must be in the trusted domains list of the wiki. The documentation also says that an empty server="" forces the embedded mode when a server is set in the administration, which a blank field cannot express. |
| plantuml | C1 clarity | type | "the type of diagram" does not say that the parameter only matters when the content has no @start tag, which the documentation states, and the values, like dot, jcckit or ebnf, are names of PlantUML engines that mean nothing to most users. |
Impact found on macro fluidity
These 4 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity 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.