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. Every macro in scope is audited against the same usability criteria. The audit results in JIRA issues, macro by macro, and in a list of behaviours that differ between macros and should be made consistent.

The scope is the 68 macros of XWiki Standard and of the Recommended extensions that are fully open source. Deprecated macros replaced by another one, macros from Pro extensions and macros from non recommended extensions are left out.

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

Contents

• Usability analysis: start here to follow the audit. Charts of the progress and the results, the history of the audit day by day, the results by criterion and by macro, and the copy of the criteria the audit uses.
  • 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.
  • 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.
• Usability criteria: what every macro is checked against, and how to audit a macro. This is the working version, the audit uses the copy frozen in the Usability analysis.
• Per macro analysis: one page per macro, with its audit, its parameters, screenshots of its dialogs, the problems found and the JIRA issues that cover them.
• 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.
• Documentation status: where each macro is documented today, and whether that documentation has been migrated to the new documentation tree.
• Appendix - Discarded research: research gathered along the way that ended up not being used.