WMDE Technical Wishes/VisualEditor template dialog improvements

This page documents the development progress of and discussions about the project VisualEditor template dialog improvements from the focus area "Make working with templates easier". You can find general information about that area and how we chose the projects in that area on this page.

We welcome comments and questions about this project on the discussion page.

VisualEditor template dialog improvements
Status	deployed
Focus area	Templates
Phabricator	T296759 T286992 T284203
Responsible	Technical Wishes Team

Improvements in a nutshell

• An overview of the biggest changes in the VisualEditor

• Better overview of available parameters
• Make adding parameters easier, including search filters
• Make important information more visible
• Improved documentation
• Larger dialog window with more spacing
• Warnings to prevent data loss
• Make adding files easier (cancelled)

Status and next steps

• Done: November 24th, 2021: deployment of all changes on
  • German, Greek, Malay, Twi, French, Hungarian, Turkish, Hebrew, Finnish and Dagbani Wikipedia
  • on English Wikivoyage
  • on Nauruan Wiktionary
• Deployment on more wikis happens in two steps:
  • bundle 1: a bigger dialog window and inline descriptions (those changes are marked as bundle 1 under "Implementation")
    • Done: March 9, 2022: all remaining wikis except English Wikipedia
    • Done: March 16, 2022: on English Wikipedia
  • bundle 2: deployment of all the other changes
    • Done 10 May, 2022: all wikis except English WP
    • Done : May 17, 2022: deployment on English Wikipedia
      

Problems

Our research has identified several problems with the existing interface for editing templates in the VisualEditor. Among other things:

• It’s hard to know what the template expects from you, in terms of both content and formatting. Currently, descriptions with essential instructions are hidden away in the info icon, leaving people guessing.
• It’s unclear why the dialog looks the way it does. Why are there no descriptions? Why are the parameter names so confusing? Why are some fields present and some absent? The various configurations are poorly explained, and it’s unclear where to look for help or instructions. In particular, less experienced editors are often unaware that templates and TemplateData are community-generated content.
• Templates can be complex and very large: some have over 100 parameters. Under the current design, getting an overview is difficult, as is understanding the template’s many options within the template and finding the parameters you need. It’s exceptionally difficult to add new parameters using the existing “add more information” dropdown if you want to add more than one or don’t know exactly what the options are.
• In particular, it’s difficult to add images. You have to know about Wikimedia Commons and understand that, to add an image, you have to open Commons in a new tab, find an image there, and then copy the exact file name back to the VisualEditor dialog. You need to know exactly how to write the image name, and you get no feedback when you make a mistake.
• Users often complained about the dialog’s small size, saying that it made their work more difficult because it felt like being forced to look through a tiny window. The current window size is insufficient for the complexity of the work and the amount of information it must contain.

• The previous template dialog in VisualEditor
• 
  Collapsed view
• 
  Expanded view

Goals

Help users understand what information is needed and how to format it, so that:

• Less experienced users can easily make small edits without accidentally breaking the template or page, and without needing to fully understand the complexities of templates.
• Experienced but less technical users can perform more complex edits without needing to edit source code.
• Experienced technical users will spend less time cleaning up.

Implementation

Implementation for VisualEditor and new Wikitext mode

The implementation focuses on the VisualEditor and the new wikitext mode, because research has shown that there are particularly many problems when using templates in the VisualEditor (summary). Because the new wikitext mode (beta feature) uses the same template dialog, the changes also take effect there.

The following improvements were made to address the problems described above:

Sizing

bundle 1 The size of the dialog will be significantly larger (sidebar and main area); better spacing will make it easier to work with the complex content and to see more at a glance.

Main dialog

• bundle 1 Making the information required by parameter fields more visible. We will move the parameter name, description and special messages, such as examples (if defined in TemplateData), to a prominent location above the input field. Long texts will be collapsed. Required fields will be clearly marked by an asterisk next to the field label, making it easier to focus on the content. We'll more clearly indicate the data a template expects and how it should be formatted, thereby reducing the research, knowledge and cognitive load required to work with a template. Hopefully our improvements to the process of adding template content will also help keep mistakes and trial and error to a minimum.
• Writing context-specific help messages for templates. Users will get an explanation of what they’re seeing that varies according to whether a template has TemplateData or not, whether  the parameters can be auto-generated, if the template is meant to work without parameters and if there is multi-part content. Each variation will also provide a link to the right place for users to look for help, including the template’s own page and its documentation.
• Removing the [[ ]] button. Tests have shown that most users don’t understand the function of the [[ ]] button. In addition, the functionality is no longer necessary in the first place; parameter fields already accept wikitext. Removing the button will reduce confusion and improve accessibility, making it easier to tab through fields quickly.
• Changing the visibility of adding undocumented parameters. We will retain this existing feature but only show it when it’s needed. In usability testing, we found that inexperienced users were confused by the ability to add a parameter and thought they were changing the template itself. As a result, the new component titled “Add undocumented parameter” gets its own input and clear instructions about when it’s needed. The component for adding undocumented parameters will appear if the template lacks documentation (TemplateData) and in cases where parameters cannot be auto-generated. It will also appear whenever at least one undocumented parameter has already been added.
  • If you would like to add an undocumented parameter and the input is not visible, you can use a shortcut to make it appear: Ctrl+Shift+D
• A warning appears, when you have edited a template and are closing the dialog via back button or "closing x" without saving
• Improving documentation. We will improve the documentation for the VisualEditor Template dialog and link to it directly from the dialog, providing easy access to more in-depth information.
• The planned improvements to make adding files easier had to be cancelled, unfortunately.

Sidebar

• The sidebar will display all parameters available for this template as defined in TemplateData. You can easily see all the options and add many parameters at once.
• Checkboxes will indicate which parameters appear in the main dialog. You will be able to quickly add a parameter by checking it and remove it by unchecking it. Required parameters will be selected by default and can’t be unselected; suggested parameters will be selected by default; optional parameters will be listed but not selected.
• You will be able to filter all available parameters with a search field. When a search term is entered, it filters both the list in the sidebar and in the main area to help you find both parameters that you would like to add and parameters that are already part of the template invocation.
• Unused parameters can be hidden. This is the default for template invocations that consist of several templates, to make the sidebar more manageable.
• The sidebar will serve as a table of contents: you can click on the name of a parameter to jump to its input field in the main dialog.
• In the desktop view, the sidebar will always be open (on mobile it’s collapsed by default).
• The toolbar at the bottom contains a few advanced options which are only relevant for multi-part content. To reduce confusion, this toolbar will be hidden for single template invocations (the most common way templates are invoked) and displayed only when editing existing multi-part content.

New keyboard navigation

For users who prefer keyboard navigation, we have created new ways to move between elements.

• When parameter list is focused in the sidebar:
  • Use arrow keys to move been parameters
  • ↵ Enter: selects parameter and moves focus to the main area to add the value
  • Spacebar: selects the parameter but keeps the focus in the list (allows users to easily add many parameters at once using the keyboard)
• When editing multi-part template content: all the tools in the toolbar can be used with shortcuts. First, tab to the template name or wikitext title in the sidebar that you want to edit and press Spacebar to select it.
  • To move the content up: Ctrl+⇧ Shift+↑ (⌘ Cmd+⇧ Shift+↑ on Mac)
  • To move the content down: Ctrl+⇧ Shift+↓ (⌘ Cmd+⇧ Shift+↓ on Mac)
  • To delete: Ctrl+⌦ Del (⌘ Cmd+⌦ Del on Mac)
• If you would like to turn a single template into a multi-part template but the toolbar is not visible, you can use shortcuts to do so. These shortcuts can also be used if the toolbar is visible.
  • Add a template: Ctrl+D (or ⌘ Cmd+D on Mac)
  • Add wikitext: Ctrl+⇧ Shift+Y (or ⌘ Cmd+⇧ Shift+Y on Mac)
• If you would like to add an undocumented parameter and the input is not visible, you can use a shortcut to make it appear: Ctrl+⇧ Shift+D