|
| Description: |
The names and descriptions of the wikimacrocontent and wikimacroparameter macros, and of their parameters, use the macro identifiers written in camel case and repeat the names, so a wiki macro author cannot tell where the macros work or what to type.
The macros to change, with the file where most of the fix is done:
* wikimacrocontent: defined in [WikiMacroContentMacro.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-wikimacro/xwiki-platform-rendering-wikimacro-store/src/main/java/org/xwiki/rendering/wikimacro/internal/WikiMacroContentMacro.java], where its descriptions are written.
* wikimacroparameter: defined in [WikiMacroParameterMacro.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-wikimacro/xwiki-platform-rendering-wikimacro-store/src/main/java/org/xwiki/rendering/wikimacro/internal/WikiMacroParameterMacro.java], where its descriptions are written.
The description of wikimacroparameter must also say when the value of the parameter is edited in place, so that a wiki macro author knows why it is not in a given case.
h2. KOs covered
||Macro||Criterion||Parameters||Problem||
|[wikimacrocontent|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacrocontent/]|D1 wording| |"WikiMacro Content" is the macro ID spelled with capitals, and "WikiMacro" is the camel-case form of "wiki macro", the words the documentation and the editor use for this feature. A developer reads it, so technical words are fine, but the measure asks for no camelCase and "Put Footnotes" is the same kind of ID split into words. The French and German names are the English one.|
|[wikimacrocontent|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacrocontent/]|D2 summary| |"Display editable content of a wikimacro." repeats the name and adds only "editable", and it spells "wikimacro" as one word. It does not say where the macro works. It does something only in the code of a wiki macro, where it shows the content the caller passes, and only when that content is of type Wiki, and on a normal page it renders nothing at all. The documentation says both, see L2.|
|[wikimacroparameter|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacroparameter/]|D1 wording| |"WikiMacro Parameter" is the macro ID spelled with capitals, and "WikiMacro" is the camel-case form of "wiki macro", the words the documentation and the editor use for this feature. A developer reads it, so technical words are fine, but the measure asks for no camelCase, and "Put Footnotes" is the same kind of ID split into words. The French and German names are the English one.|
|[wikimacroparameter|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacroparameter/]|D2 summary| |"Display editable parameter of a wikimacro." repeats the name and adds only "editable", and it spells "wikimacro" as one word. It does not say that the macro does something only in the code of a wiki macro, where it shows the value that the caller passes for the parameter, nor that the value is edited in place only for a parameter of type Wiki. On a normal page it renders nothing.|
|[wikimacroparameter|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacroparameter/]|C1 clarity|{{$content}}|The Edit Macro dialog shows a Content field, named "Content" with no description in English, and the macro ignores any content: its class declares an optional content with DefaultContentDescriptor(false) and execute() never reads it. Text typed in it is lost silently, see E2.|
|[wikimacroparameter|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacroparameter/]|C1 clarity|{{name}}|The field is called "name" and its description is "name", the ID repeated, in every language. It does not say that it is the name of a parameter of the wiki macro whose code holds the call, nor that an unknown name shows nothing. Technical terms are fine for a developer macro, but a description that says nothing is a KO, like the one of the id of attachmentGalleryPicker.|
|[wikimacroparameter|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/wikimacroparameter/]|E3 nesting|{{name}}|Minor. Called from a wiki macro in a list item, a table cell or a box, or at the top level, the value of the parameter is never edited in place in the editor, and nothing says why or when it is. Partly covered, see below.|
h2. Impact found on macro fluidity
These 6 7 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C1 clarity, D1 wording, D2 summary , E3 nesting of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. 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.
The E3 nesting KO of wikimacroparameter is only partly covered here, for explaining when the value is edited in place. The same KO is also covered by XWIKI-19954, which adds the editing in place of the content of macros that are not standalone. |
|
