Wiki source code of Usability criteria
Last modified by Lucas Charpentier on 2026/10/13 11:46
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{warning}} | ||
| 2 | These criteria are a draft proposal and are yet to be validated by the community. | ||
| 3 | {{/warning}} | ||
| 4 | |||
| 5 | 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. | ||
| 6 | |||
| 7 | To audit a macro against these criteria, follow the [[audit process>>doc:Proposal.WYSIWYGusabilityofXWikimacros.Analysis.Audit process.WebHome]]. | ||
| 8 | |||
| 9 | 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. | ||
| 10 | |||
| 11 | {{info}} | ||
| 12 | Macros already marked as deprecated or internal do not need to be audited against these criteria, since they are hidden from insertion. | ||
| 13 | {{/info}} | ||
| 14 | |||
| 15 | {{toc/}} | ||
| 16 | |||
| 17 | == 0. Classification == | ||
| 18 | |||
| 19 | * **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]]. | ||
| 20 | * **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. | ||
| 21 | * When a macro sits in between, classify it by what makes up most of its output, and note the reason. | ||
| 22 | |||
| 23 | == 1. Discovery == | ||
| 24 | |||
| 25 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 26 | |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]] | ||
| 27 | |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.|- | ||
| 28 | |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]] | ||
| 29 | |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.|- | ||
| 30 | |||
| 31 | == 2. Learnability == | ||
| 32 | |||
| 33 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 34 | |**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]] | ||
| 35 | |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.|- | ||
| 36 | |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.|- | ||
| 37 | |||
| 38 | == 3. Insertion == | ||
| 39 | |||
| 40 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 41 | |**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.|- | ||
| 42 | |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.|- | ||
| 43 | |**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.|- | ||
| 44 | |**I4**|cursor|After insertion, the cursor is in the macro content, so the user can keep typing without an extra click.|Wrapper|-|- | ||
| 45 | |**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]] | ||
| 46 | |||
| 47 | == 4. Configuration == | ||
| 48 | |||
| 49 | {{info}} | ||
| 50 | 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. | ||
| 51 | {{/info}} | ||
| 52 | |||
| 53 | |=ID|=Name|=Description|=Applies to|=Applies to content|=Measure|=Example | ||
| 54 | |**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]] | ||
| 55 | |**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.|- | ||
| 56 | |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]] | ||
| 57 | |**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]] | ||
| 58 | |**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.|- | ||
| 59 | |**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.|- | ||
| 60 | |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]] | ||
| 61 | |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.|- | ||
| 62 | |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]] | ||
| 63 | |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]] | ||
| 64 | |||
| 65 | {{info}} | ||
| 66 | 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. | ||
| 67 | {{/info}} | ||
| 68 | |||
| 69 | == 5. Editing == | ||
| 70 | |||
| 71 | |=ID|=Name|=Description|=Applies to|=Measure|=Example | ||
| 72 | |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]] | ||
| 73 | |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]] | ||
| 74 | |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]] | ||
| 75 | |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]] | ||
| 76 | |**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]] | ||
| 77 | |**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]] | ||
| 78 | |||
| 79 | == Discarded criteria == | ||
| 80 | |||
| 81 | Criteria that were considered and then dropped, kept here as a record. | ||
| 82 | |||
| 83 | |=ID|=Name|=Description|=Reason | ||
| 84 | |C10|pickers|The pickers find what the user looks for. An exact title returns the page, including a parent page with many children, as in [[XWIKI-20632>>https://jira.xwiki.org/browse/XWIKI-20632]].|Merged into C4: a picker that does not find what the user looks for is not the right control. | ||
| 85 | |C11|content-optional|The content is mandatory only when the macro's behavior is ambiguous without it.|Merged into C2, which also applies to the content. | ||
| 86 | |C12|hint|When the Edit Macro dialog shows the content field, its description says what to type.|Merged into C1, which also applies to the content. | ||
| 87 | |D5|hidden|Deprecated or internal macros are hidden from insertion.|Handled automatically: the macro service hides every macro in a hidden category, Deprecated and Internal by default. Declaring that category is covered by D3. | ||
| 88 | |D6|search-id|Macro search matches the stable macro ID as well as the localized macro name, so that a macro can be found whatever the current UI language.|Merged into D4: a localized name is close to the synonyms D4 already covers. Searching by macro ID is handled by the editor for every macro, see [[XWIKI-20230>>https://jira.xwiki.org/browse/XWIKI-20230]]. Proposed on the [[forum>>https://forum.xwiki.org/t/brainstorming-usability-criteria-for-auditing-macros-in-the-wysiwyg-editor/18907/3]]. | ||
| 89 | |I6|wrap|Selecting existing text and inserting the macro wraps that text.|Handled by the editor for every macro that declares a content, so it does not differ between macros. The remaining editor gaps belong to the cross-macro findings. | ||
| 90 | |L4|compromise|When a technical limitation prevents a macro from meeting a criterion, the workaround chosen is applied the same way to every affected macro, and the limitation and its workaround are documented where users and contributors can find them.|Audit rule rather than a property of the macro, moved to How to audit a macro. | ||
| 91 | |E7|roundtrip|Editing an existing macro opens the Edit Macro dialog with its current values and the same order and groups as at insertion.|Handled by the editor: the same Edit Macro dialog is used for insertion and editing, for every macro. | ||
| 92 | |E8|preview|Note whether a live preview in the Edit Macro dialog would help, for the separate macro preview discussion. Nothing to implement yet.|Not needed: every generator macro is assumed to benefit from a live preview. | ||
| 93 | |E9|unknown-macro|An unresolved macro remains understandable and repairable in the editor: the error is at least as informative as in view mode, and the macro ID, parameters and content remain visible without data loss.|Handled by the macro system: an unknown macro has no descriptor, so every unknown macro behaves the same. Invalid values are covered by E2. See [[XWIKI-11702>>https://jira.xwiki.org/browse/XWIKI-11702]]. Proposed on the [[forum>>https://forum.xwiki.org/t/brainstorming-usability-criteria-for-auditing-macros-in-the-wysiwyg-editor/18907/3]]. |
