Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
11.1.7
-
None
-
Unknown
-
Description
The descriptions of the parameters of the JIRA macro use internal terms and do not say what to type: the content depends on the source, the fields description shows raw Javadoc markup, and the server id does not say where it is configured.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| jira | C1 clarity | $content | "The JIRA issues to retrieve" does not say what to type: one issue key per line when source is list, optionally followed by "|" and a note, or a JQL query when source is jql. |
| jira | C1 clarity | fields | The description shows raw Javadoc markup to the user, "Format is {@code id1:label1!type1,id2:label2!type2}", and does not say which field ids and types exist. The name "Fields" is fine. |
| jira | C1 clarity | id | "the configuration id of the JIRA Server URL to use" does not say where these ids are defined, the JIRA configuration of the wiki administration, nor that it is the recommended way to set the server. |
| jira | C1 clarity | maxCount | The label is the camelCase ID, "MaxCount", and the description, "the max number of JIRA issues to display", does not say what the preselected -1 means, the limit of the JIRA server. |
| jira | C1 clarity | parameters | The name "Parameters" says nothing, and the description, "extra parameters for sources, displayers and field displayers", uses internal terms and gives neither the format, comma-separated name=value pairs, nor an example of a parameter, like field.url.label. |
| jira | C1 clarity | source | "how JIRA issues are defined (e.g. "jql", "list")" does not say that it decides what the content holds, issue keys or a JQL query, and the "e.g." suggests other values while there are only two. |
Impact found on macro fluidity
These 6 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.