Details
Major Description
The descriptions of the chart, liveData and dashboard macros, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Most parameters need developer knowledge that the descriptions do not give: the format to type, the accepted values or the unit.
The macros to change, with the file where most of the fix is done:
- chart: defined in ChartMacro.java, descriptions in ApplicationResources.properties.
- liveData: defined in LiveDataMacro.java, descriptions in ApplicationResources.properties.
- dashboard: defined in DashboardMacro.java, descriptions in ApplicationResources.properties.
The main problems:
- The source, params and content of chart, and the source, sourceParameters, filters and layouts of liveData, give no format and no list of values.
- The width and height of chart do not give their unit.
- dashboard is in the Layout category, although it shows gadgets rather than a layout, and liveData is in Content, although its parameters need developer knowledge.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| chart | C1 clarity | $content | "Input data for the chart macro (e.g. for 'inline' source mode)" does not say what to type: a table in the syntax of the page, with a header row and a first column of labels, and which cells hold the data, see the range of params. "'inline' source mode" is a developer term. |
| chart | C1 clarity | height | "The height of the generated chart image" does not give the unit, pixels, which the documentation states. |
| chart | C1 clarity | params | The label "Params" is an abbreviation of the ID, and the description, "Additional parameters for the data source", gives neither the format, key:value pairs separated by ";", nor the keys, range and series for a table, document and table for another page, and the colors and display options. Nothing says that the range is needed for the documented table, see C3. |
| chart | C1 clarity | source | "The string describing the type of input data source (e.g. xdom or inline)" uses developer terms, "string" and "xdom", the internal name of a table of another page, and does not say that an empty value picks inline when the macro has content and xdom otherwise. The "e.g." suggests other values while there are only two. |
| chart | C1 clarity | width | "The width of the generated chart image" does not give the unit, pixels, which the documentation states. |
| dashboard | D2 summary | The description "A macro to define a dashboard to fill with gadgets." mostly repeats the name, and starts with "A macro to": it does not say what the macro adds to the page, the gadgets saved on the page, or on the Source page, shown in columns. The Java description, "A macro to define a dashboard.", is overridden by the translation. | |
| dashboard | D3 category | The macro is in Layout, like container and gallery, but a dashboard is not a layout: it shows gadgets, the page tree or the activity stream, which users would rather look for in Content or Navigation, the categories of the compared generators liveData and children. Which category fits should be questioned again with the community. | |
| dashboard | C1 clarity | layout | "The identifier of the layout to use for this dashboard (e.g. columns, etc)" uses the developer term "identifier" and an "etc" for a list of values that has only one entry in XWiki Standard. The English name in the descriptor is the ID, "layout", the dialog only capitalizing it. |
| dashboard | C1 clarity | source | "The source of the dashboard macro, as a page reference, where the gadget configurations (objects) should be read from." is circular, "the source of the dashboard macro", and uses the developer terms "page reference" and "objects". It does not say the effect for the user: showing, and editing, the gadgets of another page, shared by every page that uses it. |
| dashboard | C1 clarity | style | The parameter holds a CSS class, like cssClass in other macros such as box, container or code, but it is named style, which reads as an inline CSS style: the name is inconsistent with the other macros. The description is long, four sentences, but it explains the effect of no value and of "panels". |
| liveData | D2 summary | The description "Display dynamic lists of data." mostly restates the name, "live" as "dynamic" and "data": it does not say that the macro adds a list of pages or objects, shown as a table or as cards, that the reader can sort, filter and page through. | |
| liveData | D3 category | The macro is in Content, while its parameters need developer knowledge, the component hints of the sources, property IDs and URL query strings, see C1. As a Content macro, every user should be able to configure it; whether its parameters or its category should change is to discuss with the community. | |
| liveData | C1 clarity | $content | "Advanced Live Data configuration (JSON)" says the expected format, but not what can be configured, where the format is described, or that the parameters override it. |
| liveData | C1 clarity | filters | "specified as an URL query string" does not give the form property=value, nor that a property can be repeated to filter on several values. |
| liveData | C1 clarity | id | "Id" and "The live data instance id." do not say what it is for: the display state is stored in the page URL under this id, so two Live Data of a page need different ids. |
| liveData | C1 clarity | layouts | "The comma-separated list of layouts" does not give the available layouts, table and cards. |
| liveData | C1 clarity | source | "The live data source to use, specified as a component hint." is technical, and does not give the available sources, like liveTable. |
| liveData | C1 clarity | sourceParameters | "The live data source parameters, specified as an URL query string." does not say which parameters, like className or translationPrefix for the liveTable source; the French description says "sous la forme d'une URL". |
Impact found on macro fluidity
These 18 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.