WMDE Technical Wishes/VisualEditor template dialog improvements

From Meta, a Wikimedia project coordination wiki
Jump to navigation Jump to search

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.

Planned improvements in a nutshell[edit]

  • 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
  • Make adding files easier (cancelled)
VisualEditor template dialog improvements
Status Done; Release Notes
Focus area Templates
Phabricator T286992 T284203
Responsible Technical Wishes Team

Status and next steps[edit]

  • Yes check.svg Done on German, Greek, Malay, Twi, French, Hungarian, Turkish, Hebrew, Finnish and Dagbani Wikipedia and on English Wikivoyage and Nauruan Wiktionary deployed November 24th, 2021
  • Deployments on more wikis planned for later in 2021.

Problems[edit]

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.


Goals[edit]

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[edit]

Implementation for VisualEditor and new Wikitext mode[edit]

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.


We’re planning the following improvements to address existing problems:

Main dialog[edit]

  • 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
  • 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[edit]

  • 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.
  • 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.[1] 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[edit]

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 of the tools in the toolbar can be used with shortcuts. First, tab to the template name or wikitext title in the sidebar and press Spacebar to select it.
    • To move up: Ctrl+Shift+Up arrow (Cmd+Shift+Up arrow on Mac)
    • To move down: Ctrl+Shift+Down arrow (Cmd+Shift+Down arrow 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

Sizing[edit]

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.

Notes[edit]

  1. Multi-part content contains one or more templates and in some cases wikitext, mainly used for unbalanced templates and templates within tables.