Description

This proposal analyses how usable XWiki macros are from the WYSIWYG editor, so that a user can insert and configure any macro without reading its documentation. It defines the usability criteria a macro is checked against, and gathers the conclusions that hold for every macro: the behaviours that differ between macros and should be made consistent, and the issues of the macro system itself.

The criteria are applied in audits. An audit checks every macro of its scope, on one XWiki version, against a frozen copy of the criteria, then reports its KOs in JIRA, macro by macro. Each audit has its own page with everything it produced. The first one is the macro audit of October 2026.

The discussion happens on the forum, in Consistency of the macro parameter table and Usability criteria for auditing macros in the WYSIWYG editor.

Contents

Analysis

What holds for every macro, whatever the audit.

• Usability criteria: what every macro is checked against. This is the working version, each audit uses a copy frozen at the time it starts.
• Cross-macro findings: the behaviours that differ between macros and should be made consistent, the issues that apply to all macros, and the technical limitations recorded during the audit.
• Appendix - Discarded research: research gathered along the way that ended up not being used.

Macro audit (October 2026)

Macro audit (October 2026): the audit of the macros in scope, done on XWiki 18.8.0 from October 2026, and the triage and report of its KOs in JIRA.

• Per macro analysis: start here to follow the audit. Charts of the progress and the results, the history of the audit day by day, and the results by criterion and by macro. Each macro has its own page under it, with its audit.
• Triage: the triage of the KOs, the existing and the new JIRA issues mapped to them, and every KO with its tickets.
• Audit process: how to audit a macro step by step, then report its KOs in JIRA, and where every part of the audit is stored.
• Audit criteria: the copy of the usability criteria every macro is audited against.
• Known issues: the JIRA issues reported before the audit, sorted by the macro they affect, to check before reporting a KO so that no duplicate is created.
• Documentation status: where each macro is documented today, and whether that documentation has been migrated to the new documentation tree.
• Out of scope macros: the macros left out of the audit, with the reason for each.