Wiki source code of Usability analysis
Last modified by Lucas Charpentier on 2026/10/13 14:05
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{include reference="Proposal.WYSIWYGusabilityofXWikimacros.Code.MacroAuditStats"/}} | ||
| 2 | |||
| 3 | This page follows the audit of every macro of the [[per macro analysis>>doc:Proposal.WYSIWYGusabilityofXWikimacros.Macros.WebHome]] against the usability criteria. The progress, the history and the results are computed from the audit of each macro page, so they are up to date as soon as an audit is saved. To audit a macro, follow the [[audit process>>doc:Proposal.WYSIWYGusabilityofXWikimacros.Analysis.Audit process.WebHome]]. The JIRA issues reported before the audit are listed by macro in the [[Known issues>>doc:Proposal.WYSIWYGusabilityofXWikimacros.Analysis.Known issues.WebHome]]. | ||
| 4 | |||
| 5 | == Progress == | ||
| 6 | |||
| 7 | {{velocity}} | ||
| 8 | #auditCharts() | ||
| 9 | |||
| 10 | #auditSummary() | ||
| 11 | {{/velocity}} | ||
| 12 | |||
| 13 | == KOs not reported yet == | ||
| 14 | |||
| 15 | {{velocity}} | ||
| 16 | #auditUnreported() | ||
| 17 | {{/velocity}} | ||
| 18 | |||
| 19 | == History == | ||
| 20 | |||
| 21 | One row per day on which macros were marked as reviewed, from the audit date of each macro, or from the last change of its page when the audit date is empty. | ||
| 22 | |||
| 23 | {{velocity}} | ||
| 24 | #auditHistory() | ||
| 25 | {{/velocity}} | ||
| 26 | |||
| 27 | == Results == | ||
| 28 | |||
| 29 | {{velocity}} | ||
| 30 | #auditResults() | ||
| 31 | {{/velocity}} | ||
| 32 | |||
| 33 | === All audit values === | ||
| 34 | |||
| 35 | {{include reference="Proposal.WYSIWYGusabilityofXWikimacros.Code.MacroAuditLiveData"/}} | ||
| 36 | |||
| 37 | {{include reference="Proposal.WYSIWYGusabilityofXWikimacros.Code.MacroParameterAuditLiveData"/}} | ||
| 38 | |||
| 39 | == Criteria == | ||
| 40 | |||
| 41 | {{info}} | ||
| 42 | This is a copy of version 15.17 of the [[Usability criteria>>doc:Proposal.WYSIWYGusabilityofXWikimacros.Usability criteria.WebHome]], the version every macro is audited against. Later changes of that page do not apply to this audit. | ||
| 43 | {{/info}} | ||
| 44 | |||
| 45 | These are the criteria every macro is audited against in the [[WYSIWYG usability of XWiki macros>>doc:Proposal.WYSIWYGusabilityofXWikimacros.WebHome]] proposal. The goal is that a user can insert and configure a macro without reading any documentation. | ||
| 46 | |||
| 47 | The criteria use the parameter metadata XWiki already supports. Each criterion has a name to refer to it, and a measure that adds any precision needed to check it. | ||
| 48 | |||
| 49 | {{info}} | ||
| 50 | Macros already marked as deprecated or internal do not need to be audited against these criteria, since they are hidden from insertion. | ||
| 51 | {{/info}} | ||
| 52 | |||
| 53 | === 0. Classification === | ||
| 54 | |||
| 55 | * **Wrapper macro:** most of its output is content the user types, and the macro decorates or structures it. Examples: warning, info, success, error, box, expand. Reference: [[warning>>doc:xwiki:documentation.xs.user.base.page.edit.warning-macro.WebHome]]. | ||
| 56 | * **Generator macro:** most of its output comes from its parameters and the context around it, not from typed content. Examples: table of contents, Jira charts, livedata, document tree. Reference: to be chosen. | ||
| 57 | * When a macro sits in between, classify it by what makes up most of its output, and note the reason. | ||
| 58 | |||
| 59 | === 1. Discovery === | ||
| 60 | |||
| 61 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 62 | |D1|wording|The macro name uses the user's words for what it produces (a warning, a diagram), not technical jargon.|All|No camelCase, code identifier or unexplained acronym.|[[XWIKI-21596>>https://jira.xwiki.org/browse/XWIKI-21596]] | ||
| 63 | |D2|summary|The macro description is one sentence that says what the macro adds to the page.|All|About 20 words or fewer, and not just a repetition of the name.|- | ||
| 64 | |D3|category|The macro is in the [[category>>doc:xwiki:Documentation.DevGuide.Tutorials.WritingMacros.MacroDefaultCategories.WebHome]] a user would expect it in. {{warning}}This is especially important for deprecated and internal macros, which are hidden from insertion only when they declare the Deprecated or Internal category.{{/warning}}|All|Compare the macro's category with the categories of the macros compared in L1. They should be the same.|[[XWIKI-25018>>https://jira.xwiki.org/browse/XWIKI-25018]] | ||
| 65 | |D4|quick-action|The Quick Actions menu finds the macro with the words a user would type, including its localized name in the current UI language and common synonyms like "note" or "callout" for info or warning.|All|The macro is in the first 5 results for its name, for its localized name in at least one other UI language, and for each synonym listed in the audit.|- | ||
| 66 | |||
| 67 | === 2. Learnability === | ||
| 68 | |||
| 69 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 70 | |**L1**|consistency|The macro behaves like the other macros of the same kind, for the mandatory content, the insertion process and its default parameter values.|All|Compare the macro with at least two macros of the same type, for mandatory content, insertion and defaults. Every difference should have an issue or a cross-macro findings entry.|[[XWIKI-23035>>https://jira.xwiki.org/browse/XWIKI-23035]] | ||
| 71 | |L2|doc-parameters|The documentation of the macro parameters is up to date.|All|The documentation page lists the same parameters, defaults and mandatory flags as the macro.|- | ||
| 72 | |L3|doc-example|The documentation of the macro contains at least one example for its most common use.|All|The example can be copied into a page and renders without error.|- | ||
| 73 | |||
| 74 | === 3. Insertion === | ||
| 75 | |||
| 76 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 77 | |**I1**|pattern|There is no macro-specific insertion behavior. The macro follows a common behavior, whether inserted from the Quick Actions menu or from the Insert Macro dialog.|All|Same steps as the [[reference macro>>||anchor="H0.Classification"]] of the same type, from both the Quick Actions menu and the Insert Macro dialog.|- | ||
| 78 | |I2|zero-config|Inserting with only default values gives a sensible result, not an error box. Generator macros may require configuration before giving a sensible result.|Wrapper (All?)|No error box in the editor, nor in view mode after saving.|- | ||
| 79 | |**I3**|instant|Inserting from the Quick Actions menu does not open the Edit Macro dialog. The macro appears in the page right away.|Wrapper|One Enter is enough.|- | ||
| 80 | |**I4**|cursor|After insertion, the cursor is in the macro content, so the user can keep typing without an extra click.|Wrapper|-|- | ||
| 81 | |**I5**|focus|When inserting a macro through the Edit Macro dialog, the essential parameters come first and the focus is on the first one.|Generator|Every mandatory parameter is visible without expanding a section or scrolling.|[[XWIKI-21362>>https://jira.xwiki.org/browse/XWIKI-21362]] | ||
| 82 | |||
| 83 | === 4. Configuration === | ||
| 84 | |||
| 85 | {{info}} | ||
| 86 | The content of a macro is a parameter like any other. The Applies to content column tells whether a criterion also applies to it. The content descriptor only declares a description, a mandatory flag, a type and an order, so the other criteria cannot apply to it. | ||
| 87 | {{/info}} | ||
| 88 | |||
| 89 | |=ID|=Name|=Description|=Applies to|=Applies to content|=Measure|=Example | ||
| 90 | |**C1**|clarity|Each parameter name and description is self-explanatory, and uses user terms.|All|Yes|States the effect and the expected value, with no technical term unless the macro targets developers.|[[XWIKI-23032>>https://jira.xwiki.org/browse/XWIKI-23032]] | ||
| 91 | |**C2**|mandatory|A parameter is mandatory only when the macro's behavior is ambiguous without it.|All|Yes|For each mandatory parameter, look for a default value that works for the most common example of L3. If one exists, the parameter should be optional.|- | ||
| 92 | |C3|defaults|The default value of each optional parameter is the value used in most cases, and the Edit Macro dialog displays it clearly.|All|No|The default is the value used in the most common example of L3, and the Edit Macro dialog shows it as a preselected value.|[[XWIKI-16040>>https://jira.xwiki.org/browse/XWIKI-16040]] | ||
| 93 | |**C4**|input-assistance|Each parameter uses an appropriate input, such as a picker or a checkbox. Pickers support both suggestion and typing for selection.|All|Yes|No free-text field is left where a picker could be used. In each picker, searching for an existing target gives consistent and predictable results.|[[XWIKI-23037>>https://jira.xwiki.org/browse/XWIKI-23037]] | ||
| 94 | |**C5**|groups|Parameters used together are in the same group, and groups appear in a logical order.|All|No|Count the parameters outside any group, then the parameters in each group. None of these counts goes above [[Miller's number>>https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two]], 7 ± 2. The group with the essential parameters comes first, and no group mixes unrelated parameters.|- | ||
| 95 | |**C6**|order|Within each group, and among the parameters outside any group, parameters are ordered by how often they are used.|All|Yes|Within each group, and among the parameters outside any group, the parameters set in the most common example of L3 come first. Importance can vary with the use case, so the auditor judges the order using that example as a basis.|- | ||
| 96 | |C7|alternatives|When several parameters are alternative ways to set the same feature, the Edit Macro dialog presents them as a unit, and requires one of them when the macro needs it.|All|No|In the Edit Macro dialog, alternative parameters appear together as one feature. When one of them is needed, the feature is marked as required.|[[XWIKI-20944>>https://jira.xwiki.org/browse/XWIKI-20944]] | ||
| 97 | |C8|advanced|Rarely used parameters are marked as advanced.|All|No|Check whether any parameter set in the most common example of L3 is marked as advanced. None should be.|- | ||
| 98 | |C9|technical|Only parameters that are meant to be edited are shown.|All|No|Compare the fields of the Edit Macro dialog with the parameters used in all the examples of the documentation. For each field that no example uses, try to think of a realistic new example that would use it. If there is none and the field is shown, it is an issue.|[[XWIKI-13363>>https://jira.xwiki.org/browse/XWIKI-13363]] | ||
| 99 | |C13|constraints|When a parameter only accepts a range or a format, the macro declares it, so that the Edit Macro dialog can reject an invalid value before submitting.|All|No|For each number or formatted text parameter, the accepted range or format is declared in the parameter descriptor, for example with a ##@Positive## or ##@Pattern## annotation, and not only checked when the macro runs. Wiki macro parameters cannot declare constraints yet, see [[XWIKI-25197>>https://jira.xwiki.org/browse/XWIKI-25197]]: record this once in the cross-macro findings and link it from every affected wiki macro.|[[XWIKI-25182>>https://jira.xwiki.org/browse/XWIKI-25182]] | ||
| 100 | |||
| 101 | {{info}} | ||
| 102 | C3 requires the default to be preselected in its field. A placeholder does not fulfill it: screen readers do not announce it reliably, it often fails contrast requirements, it disappears as soon as the user types, and users mistake it for a value that is already filled in ([[W3C WAI>>https://www.w3.org/WAI/tutorials/forms/instructions/]], [[Nielsen Norman Group>>https://www.nngroup.com/articles/form-design-placeholders/]]). A mention in the parameter description does not fulfill it either: it means the default is not declared, so the field opens empty, the user has to type the value themselves, and inserting with default values can fail I2. | ||
| 103 | {{/info}} | ||
| 104 | |||
| 105 | === 5. Editing === | ||
| 106 | |||
| 107 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 108 | |E1|wysiwyg|The macro renders in the WYSIWYG editor the same way as in view mode, or with a dedicated edit representation that keeps the meaning of the macro.|All|Insert the most common example of L3 and compare it in the editor and in view mode. Only editor elements such as the macro frame should differ. A dedicated edit representation that keeps the meaning of the macro, like the one of the Dashboard macro, does not fail E1, but note it in the audit.|[[XWIKI-23036>>https://jira.xwiki.org/browse/XWIKI-23036]] | ||
| 109 | |E2|errors|An invalid parameter value produces a message that says what is wrong and how to fix it, not a stack trace.|All|Tested with one invalid value per parameter type. The message names the parameter and the expected value.|[[XWIKI-23142>>https://jira.xwiki.org/browse/XWIKI-23142]] | ||
| 110 | |E3|nesting|The macro behaves predictably when it is placed inside a list, a table or the content of another macro. When the macro content accepts less than the rest of the page, the restriction is visible: unsupported editing features are disabled inside it, the content description says what it accepts, and pasting unsupported content shows a notification explaining why. See [[The Content Holds the Main Data>>https://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/rendering-macros/#HTheContentHoldstheMainData]].|All|Insert the most common example of L3 inside a list item, a table cell and a box macro: each one renders and can be edited as at the top level of the page. For a macro with content, also insert a list, a table and a box macro inside its content: each one either renders and can be edited, or cannot be inserted because the feature is disabled inside the content, with a notification explaining why when it is pasted. Nothing is silently dropped or broken at rendering.|[[XWIKI-23501>>https://jira.xwiki.org/browse/XWIKI-23501]] | ||
| 111 | |E4|inline-support|The inline support the macro declares matches its behavior. A macro that declares inline support works inside a sentence, and a macro that does not declare it has a technical reason to be standalone only.|All|Insert the most common example of L3 in the middle of a sentence. If the macro declares inline support, it renders inline, with no error and no block output such as a paragraph or a box breaking the line. If it does not declare it, check whether its output could be inline: if it could, the missing declaration is an issue.|[[XWIKI-15190>>https://jira.xwiki.org/browse/XWIKI-15190]] | ||
| 112 | |**E5**|empty|Empty content still renders in the editor and stays editable, with no zero-width area that cannot receive the cursor.|Wrapper|The empty area stays visible after clicking away, and one click puts the cursor in it.|[[XWIKI-23034>>https://jira.xwiki.org/browse/XWIKI-23034]] | ||
| 113 | |**E6**|inplace|The content is edited in place in the editor, with an editing experience suited to its data, such as rich text or code, not in a text area of the Edit Macro dialog.|Wrapper|The Edit Macro dialog shows no content text area, and the content can be edited where it is displayed.|[[XWIKI-19978>>https://jira.xwiki.org/browse/XWIKI-19978]] |
