WMDE Technical Wishes/Template data editor improvements

This page documents the development progress of and discussions about the project Template data editor 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.

TemplateData editor improvements
Status	Cancelled
Focus area	Templates
Responsible	Technical Wishes Team WMDE

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

Status and next steps

The planned improvements to the TemplateData editor as part of the focus area "Make working with templates easier" will no longer be implemented. In order to be able to identify the next focus area at the beginning of next year, all improvements in this focus area must be deployed before the end of 2021, and due to delays in the schedule, implementation of these changes will not be possible in time. In addition to other delays, the extensive improvements to the VisualEditor template dialog are taking more time than originally estimated.

"Make working with templates easier" is the first focus area since the working mode was changed in the Technical Wishes project. In working on templates over the past two years, we have learned that MediaWiki software can present unpredictable challenges and often requires refactoring before changes can be made. Therefore, it is almost impossible to definitively predict which improvements can be implemented in a given timeframe. For the work on the next focus area we have learned that a ready-made list of features to be implemented cannot be defined from the beginning and the team plans to take a more flexible approach to planning.

TemplateData

TemplateData consists of metadata used to customize how the VisualEditor and Template Wizard present template parameters for input. It can be managed in the TemplateData editor or edited directly in JSON. It is often found on the given template’s /doc subpage, where it can then be edited.

Current problems

• The TemplateData editor does not provide sufficient information to understand how changes will impact how a template appears in the VisualEditor and TemplateWizard. For example, it’s not clear what effect changing a parameter’s type will have, nor are the differences between Name, Label, and Alias. The editor lacks instructions, descriptions, and links to helpful documentation.
• The differences between some settings are very subtle and confusing, calling all the more for additional help. For example, users often have trouble understanding the difference between Example, Default, and Autovalue.
• Navigation within the editor can be difficult, particularly when trying to add TemplateData for a new parameter. Currently, after adding the title, you must find it again in a list before adding properties, instead of immediately seeing a dialog window.
• Currently you can check all three properties: Required, Suggested, and Deprecated; however, these properties are mutually exclusive, and a fourth option, Optional, is invisible. Parameters have this priority by default, but the editor does not make this clear.
• The parameter list employs the wrong icon, obscuring the fact that parameters are draggable. Dragging allows users to create the ParamOrder, which then determines the order in which users editing an invocation in the VisualEditor will see them.
• The parameter property “type” is underused. Most parameters are labeled “unknown” or “string”, but as of this writing thirteen different types exist. Parameter types can provide guidance to the user; they determine the input fields and options that users editing an invocation in the VisualEditor will see.
• Finding the right place to add TemplateData can be difficult, since that data can be added to the template page itself, and people often forget to navigate to the subpage. Editing the template page itself overwrites existing TemplateData and can cause big issues. As it stands the warning is easily missed and confusingly worded.
• Perhaps because of the reasons above, TemplateData generally is not yet used to its full potential, which means template users don’t always receive the information they need to understand how a template is meant to be used.

Some planned changes. Note: This is a draft.

Planned implementation

We plan these improvements to address existing problems:

• We will improve documentation for the TemplateData editor and link to it directly from the editor, providing easy access to more in-depth information.
• We will make more noticeable the warning that appears when TemplateData already exists on a template’s subpage, and we will explain the state of affairs more clearly, hopefully preventing users from unintentionally overwriting existing TemplateData.

In the main dialog

• The parameter list will display parameter types, providing more information than currently shown. At the moment, tags in the parameter list are aliases, often the same word as the parameter name. Prominently displaying parameter types encourages their use, which will improve data quality by better regulating the data that users insert into a template.
• Small UX changes:
  • Text in the user interface (buttons, titles) will be changed to provide more information about the meaning of fields and actions.
  • The icon in the parameter list will be changed to make clear it’s draggable.
  • After adding a parameter, its property dialog will open automatically, saving users time when adding new parameters and potentially encouraging users to provide more complete TemplateData.

In the parameter properties dialog

• All fields and their labels will be in one column, as opposed to the current side-by-side layout, making it easier to scan through the dialog as well as allowing for descriptions to be displayed above the fields, consistent with the proposed changes to the VisualEditor.
• Collapsible descriptions will be added for parameter properties making it clearer what the fields are for, what the differences between fields are, and the impact that changing them will have.
• The order of parameter property fields will be changed to list most-used properties first.
• Text fields will resize when the new content is longer than one line. This should make editing easier, as well as providing descriptions and instructions.
• Parameter priority will be displayed more clearly. Users will be able to select only one of the four options from a dropdown, and the default value (optional) will be marked as such.
• The overall design of the dialog will be more balanced. The dialog will be larger with different spacing to improve readability and orientation.
• We will introduce a new parameter property, “suggested values”, which  presents a list of predefined values to select from.