WMDE Technical Wishes/Templates

From Meta, a Wikimedia project coordination wiki
Templates!

Make working with templates easier[edit]

How can working with templates become easier? That's the question the Technical Wishes team at Wikimedia Deutschland will focus on for two years. This focus was set by the 2019 Technical Wishes Survey on German Wikipedia.

The team sets out to find solutions for different problems that people on the wikis encounter when they work with templates. Improving individual templates is not part of the project. Instead, it's about finding concepts that generally make it easier to work with templates.

Projects[edit]

Based on the research results, feedback on the prototypes, interviews with Wikipedians and further input from the communities, we started the first projects in September 2020.

Project on some wikis on all wikis
Bracket Matching
  Done
  Done
Improved Color Scheme of Syntax Highlighting
  Done
  Done
Line Numbering
  Done
  Done
for the template namespace
Suggested values for template parameters
  Done
  Done
Finding and inserting templates
  Done
  Done
Removing a template from a page using the VisualEditor
  Done
  Done
VisualEditor template dialog improvements
  Done
  Done
TemplateData editor improvements
  Cancelled
  Cancelled

Additional improvements[edit]

While working on the projects, our team also took care of a few other issues that we came across:

Notable[edit]

  • <templatedata> supports a “paramOrder” where one can specify a preferred order in which a template’s parameters should appear in VisualEditor. Alternatively, the actual order of the parameters in the “params” section can be changed. This is now respected when there is no “paramOrder”. T216808
  • Significantly improved performance of the wikitext syntax highlighter. T270317
  • Significantly improved loading time of the template editor when editing large multi-part templates, e.g. tables where each table row is a template. Note that it might still take up to a minute in extreme situations, but is a lot faster on average. T296335
  • Improved keyboard navigation and screen reader support (e.g. utilizing ARIA standards) in the VisualEditor template dialog. T289653
  • VisualEditor works much better with templates that are supposed to be used with the “subst:” prefix.
  • The TemplateData API works better together with other API modules as “generators”. The responses from both API modules will be merged. Before the data from the generator was not visible. T274907

Minor[edit]

  • A few smaller improvements to the wikitext syntax highlighter to make it understand certain edge-cases better. Example: T277767
  • Fixed editor losing focus when switching syntax highlighting on/off. T298488
  • FileImporter now also supports syntax highlighting in the step where one can fixup the file description page before the actual import is started.
  • The interactive TemplateData editor now uses a proper user-friendly widget to manage aliases, instead of a comma-separated string. T285284
  • <templatedata> now validates “aliases” and “suggestedvalues”. Both need to be lists of strings. T297386
  • Made auto-detection of template parameters in the TemplateData API more reliable. Example (one of multiple): T290322
  • A TemplateData documentation table can be sorted by the parameter’s priority: required → suggested → optional → deprecated. This is now done numerically instead of alphabetically.
  • The TemplateData documentation table appears more clean with less non-essential bits, e.g. not sortable when there is nothing to sort.
  • Fixed the TemplateData editor accidentally adding empty “autovalue” fields. T295074

History[edit]

  • Done Research of problem areas, presented on Meta and dewiki
  • Done First ideas for solutions are presented and discussed on Meta and dewiki
  • Done Ideas are revised, and tested in usability tests
  • Done September 2020: Start of development work

For the status of the individual projects, see the table above.

Identifying the projects[edit]

Over several months, an interdisciplinary team did intensive research into potential problems and improvement requests associated with templates, as seen from both a technical point of view and from that of a user. In the box below you can see a summary of that research:

Research

Over the past months, an interdisciplinary team has intensively researched which problems and improvement requests exist in the area of templates from both the user and the technical point of view. The results are based on the following:

  • Interviews with active members of Wikimedia projects on Wikimania, WikiCon as well as remote interviews. A total of 19 interviews were conducted with users from as many different backgrounds as possible: different working methods (e.g. Visual Editor / Source Code Editor), different areas of work (use of templates / writing of templates), new and experienced contributors, from different Wikis, different origins, and of different ages and gender.
  • Evaluation of all old surveys on "TechWishes" in the German Wikipedia and their equivalents on Meta
  • Evaluation of the discussion pages for this wish, the voting page, the pages of the template- and technical workshop, as well as the help pages for templates
  • Evaluation of the problems reported at the Tech on Tour
  • Viewing of several hundred, up to 15 years old, tickets on Phabricator about MediaWiki templates and related keywords
  • A workshop about templates at WikiCon 2019 to find out more about how to work with templates
  • Exchange with the Wikimedia Foundation about its past and potential activities regarding templates

The research has revealed numerous problems and suggestions for improvement. There are two large target groups: those who work on templates and those who use them. Problem areas were identified for both target groups:

People who work on templates have problems with: People who use templates have problems with
  • the template syntax
  • insufficient developer tools
  • historically grown templates
  • Maintenance of existing templates
  • the overview and findability of templates
  • the documentation of templates
  • learning how to use templates
  • the handling of templates in the Visual Editor
  • the social values and norms that have formed around the use of templates.

Most of the problems and suggestions for improvement appeared several times and in different contexts during the research, which shows their great importance. The most frequently mentioned problems in these problem areas can be found here.

As always, feedback is welcome. For example, if you think that something has been overlooked during the research, or that other criteria should be considered for the next steps, please write to us on the discussion page.

Following this first phase, further research was done to determine the improvements that could be implemented. We examined a number of improvement ideas for their feasibility, effort, potential value and any possible disadvantages. The goal was to have improvements for both template users and for template creators & maintainers.

Based on that examination, we created basic prototypes to share and further discuss possible projects, which you can see in the following box:

Early prototypes

In the autumn of 2019, the team carried out comprehensive, interdisciplinary research in the subject area (see above); the result of this research is the list of problems in the subject area published here. Since then, research has been underway to determine which improvements could be implemented. To this end, numerous ideas for improvements were examined for their feasibility, effort, potential value and possible disadvantages.

Over the coming weeks, a series of simple prototypes (first draft designs) for possible projects will be published here regularly. Everyone is invited to evaluate and comment on them. For a balanced picture, feedback is sought from Wikimedians with different levels of experience, working methods and fields of activity. Based on this feedback, the Technical Wishes team will consider whether to implement the ideas, revise them again, or discard them in favor of others. Depending on the outcome of this prototyping phase, there may be another round of new ideas to provide feedback on later in the year.

Feedback on the prototypes is always welcome. However, timely feedback (within two weeks of posting) on prototypes can be used to feed directly into the development of the next prototypes.

In order to get an even deeper understanding of the issues users face, there will also be remote interviews and user tests with Wikimedians in parallel to the onwiki feedback rounds - we are still looking for volunteers! If you would like to volunteer, you can register here. Please enter the keyword "templates" in the comment field.

Important: Since we want to present new prototypes regularly in the coming weeks and we don't want to flood users' inboxes, we ask all interested people to watch this page.

Prototype 1: Featured Templates and Search Filters[edit]

This proposal consists of two parts: Search filters to find templates and the introduction of “featured templates”. The aim of this proposal is to address the frequently mentioned need for better "overview and findability of templates". This proposal should make it easier for Wikimedians to find the right template without searching through other articles for a suitable one to copy and paste.

Search filter for templates[edit]

Both the Visual Editor and the TemplateWizard in the Wikitext Editor currently have a simple input field with auto-completion to select the desired template. At the moment templates can only be easily added here if you know the exact name of the template you want to insert. We plan to extend this to a search with filter options, so that it is easier to find the desired template. Through the filters, the search results can be narrowed by type of template (infobox, source, etc.) or by subject area (biographies, animals, etc.).

Featured templates[edit]

The second part of this proposal is the introduction of featured templates, following the example of featured articles, list and images. As with these, the criteria and processes of designating templates as ‘featurable’ are in the hands of the community. The featured templates would be shown more prominently in the search described above and suggested to users. The designation of featured templates could provide an incentive to improve existing templates instead of creating new alternatives.

The animation below shows a rough draft where you can see how these two features could work together. At the current stage the emphasis is not on the implementation details, but whether these ideas are worth pursuing further.

When the user clicks on "Insert template" in the Visual Editor a modal window opens. In this window, it is possible to search for featured templates filtered by category and type. A more detailed, larger version of this could be found on a new special page.

Feedback[edit]

We are looking forward to any kind of feedback. Do you think these two suggestions are suitable to simplify the process of finding the right template and would this make your work easier? Should we follow up on these suggestions? If possible, please tell us if you consider yourself more of a template user or template creator and more of a newcomer or a power user.

Please leave the Feedback here.

Thank you for the valuable feedback on the two parts of the first prototype as well as the numerous other ideas, suggestions and comments. We won't pursue the idea of featured templates, but will continue looking into ideas related to findability. We will be sharing another prototype about the latter for additional feedback. We appreciate all the suggestions, many of which coincide with our research, which makes us confident that we will end up with projects that will take Wikipedia and its sister projects forward.

Prototype 1 Update: Template Finder[edit]

Back in March, the Technical Wishes team shared a first prototype: Featured Templates and Search Filters. It consisted of a search with filter options and the introduction of featured templates, similar to featured articles and images. We received a lot of feedback for that prototype. Thanks a lot for all your ideas, questions and comments.

After carefully reviewing the feedback and investigating several possible directions, the next prototype we would like to propose is a refined Template Finder as a standalone feature without Featured Templates. It builds upon the previous proposal but searches all templates on a wiki. Additionally, it has different types of filters and ways of exploring the results. Ideally, this specialized search would allow users to discover new templates to meet their specific needs and help experienced users who maintain templates to easily find the templates needing attention.

The video shows an example of how a search for a template might look like in the future.

This walkthrough video begins in Visual Editor, but we would be able to provide links to the Template Finder from the TemplateWizard in the source editor, Advanced Search, and potentially elsewhere. As a standalone page, there are many options for integration and the goal is to ensure that it would be accessible to anyone who might find it useful. The video then shows a user completing a search and narrowing the selection of templates by using the available filters. For more detail on the possible features, see the individual proposals below.

1a. Adjust search algorithm[edit]

Currently, the search for templates is unsatisfactory as it does not display all suitable templates to users (too narrow) while at the same time leading to only loosely related pages (too broad).

Here are some potential ways that search results could be improved. Please note that not all proposals would necessarily be implemented.

  • Remove documentation pages from search results
  • Order of words does not affect results, meaning that the search term could exist at any point within the template name, not just at the beginning
  • Look for search term in the template description, not just the template name

1b. Filter search results by[edit]

Templates are mostly created for specific fields of application. Filters could help to find the right template for the use case in mind. Please note that the proposal includes some filters based on existing TemplateData (machine-readable metadata about individual templates) while some would require adding new fields. This content would not be added by the Technical Wishes team, but would be flexible and added on a per wiki basis by the Community based on their needs.

  • Intended Namespace:
There are several namespaces on Wikipedia such as article pages, discussion pages and project pages. As most templates only make sense in the context of a certain namespace, this would be added as a filter (Information would need to be added to TemplateData).
  • Template Type:
Wikis have different template types such as banners, citations or stubs. The exact template types differ from wiki to wiki. Every community would be empowered to set their own template type system in TemplateData and filter by this.
  • Category:
The goal with category filters would be to make existing categories more visible and explorable. This does not include changes to the category system itself or the way categories function. When filtering by category, only categories used by templates in the current search results would show up.
The displayed categories are then ordered based on which contain the most templates, so that they are ordered by relevance.
As there are many categories, users could also start typing to find the one they want.
  • Has/Missing TemplateData:
The search could allow filtering for templates that do or do not have TemplateData. This might be helpful to those maintaining templates, as well as users who are looking for a template that works easily within the visual editor.
Additionally, it would be possible to search using only filters without any search terms, for example to easily compare all templates in a category of a specific type.

1c. Sort search results by[edit]

  • Relevance:
Orderings templates by their relevance, based on the current advanced search algorithm, adjusted as mentioned in 1a.
  • Alphabetical order:
Ordering templates alphabetically by their name.
  • Popularity:
Ordering templates according to how often they are used, with the most used at the top.

1d. Display additional information in the results to facilitate template comparison[edit]

  • Preview:
The exact implementation and feasibility still needs more investigation, but ideally an example invocation (not an image) would be displayed. If no example invocation is available, the fallback plan would be to show a default/empty invocation. If a preview is missing or broken, it would display a button leading users to the TemplateData where it could be updated.
Note: The implementation would need significant investigation and discussion with the Community, but we believe that the benefits could also be significant.
  • Description:
The search results would display the description provided in TemplateData. As the examples show, most templates are currently missing the required information. There would be an info icon encouraging users to add descriptions to fill in the gaps.
  • Layout:
TemplateData already contains information on whether a template is inline or block formatted. This could easily be displayed. If useful, this could also be added as a filter. Please let us know if a filter for layout would be useful for you.
  • Number of Parameters:
The number of parameters is a nice indicator of both complexity and type of template. This would also not require additional TemplateData.

1e. Template quick view[edit]

The quick view would show more detailed information without needing to open a new page. It would focus on information needed to:

  • properly use the template,
  • compare templates in detail, and
  • select the right template.

It would contain:

  • Name of the template
With a button to easily copy the name of the template for use in the visual editor’s TemplateDialog and the source editor’s TemplateWizard (the dialog windows for inserting templates).
  • Wikitext
A box showing the source code, with a button for easy copying of the snippet, would allow source code editors to easily use a template.
  • Link to the documentation page
Would direct users there for help.
  • Link to all existing pages using the template
Thus providing users with examples.

1f. Show all templates used in an article[edit]

There is one more idea not included in the video: If users put the name of an article as the search term, all the templates used within the article would be displayed in the table below as search results.

Feedback[edit]

We are looking forward to any kind of feedback either on the talk page or in the survey in this section. Please note that not all features will necessarily be implemented, so feedback is very useful in helping prioritize. You are welcome to leave comments on any aspect of the design, but here are a few questions as a starting point:

  • Do you think the Template Finder would simplify the process of finding the right template? How?
  • Which feature is most useful? Which feature adds the least value?
  • How do you see the Template Finder fitting into existing workflows?
  • The expansion of TemplateData would increase the amount of machine readable information about templates and greatly improve the usefulness of this feature but would require community effort as well. What do you think about this impact?

Prototype 2: Improve Syntax Highlighting[edit]

Since 2018, the Wikitext editor includes syntax highlighting. This feature displays the source code with different colors, backgrounds and text styling according to their category. This should help the reader to understand the code and to orientate themselves better in the source code. Syntax highlighting can be used in both the article namespace and the template namespace (and most others). So it can help both when editing and using templates. But in more complex situations - especially when working with nested templates and when editing complex templates - the current syntax highlighting reaches its limits. In these prototypes, the aim is therefore to improve this function. We have five suggestions for this, which are roughly sketched below. As with all prototypes in this project, these are sketches of the ideas we want to hear your opinion about. Not all ideas will necessarily be implemented.

Prototype 2a: Active section highlighting and elimination of other background highlighting[edit]

Active section highlighting and elimination of other background highlighting

Currently, syntax highlighting colors the text background if the text is within a template or a so-called ParserFunction. When working on templates or editing pages with many nested templates, this can lead to almost all text being highlighted, thus creating confusion instead of clarity. This suggestion is therefore to not color the background of these texts in general and instead only highlight the innermost function or template in which the cursor is currently located. In the graphic, the cursor is located at the selected position within the 'if' function, so the entire area of this 'if' function is highlighted with a red background. This makes it easier to see what belongs together both as someone writing code and as someone looking to understand what another user has written.

Prototype 2b: Bracket matching[edit]

Bracket matching

The template syntax is known for its many curly brackets. Since templates, template variables and parser functions use different numbers of curly brackets, it can be difficult to identify which brackets belong together when developing templates or when using nested templates. Many source code editors and IDEs outside of the Wikimedia projects have a "bracket matching" function for this problem: If the cursor is next to an opening bracket, the corresponding closing bracket is highlighted and vice versa. Ideally, the functionality could also be extended so that not only the single associated bracket is highlighted, but all brackets belonging together are highlighted. In the sketch, for example, the cursor next to a closing parenthesis and thus the four curly brackets that form the beginning and end of the 'if' function are highlighted.

Prototype 2c: Bracket closing[edit]

Typing curly brackets varies in complexity depending on the keyboard. In order to be able to type faster and not forget closing brackets, another known function from development environments could be built in: if you type an opening brace, the closing brace is automatically inserted and the cursor is placed between the brackets. For example, if you type {{{, you automatically get {{{|}}} and the cursor is in the middle of the brackets, so you can continue typing the name of the variable. In implementation, there would be a way to toggle the function on and off.

Demonstration of how white space highlighting could help working with templates

Prototype 2d: Highlight whitespace that affects formatting[edit]

Depending on the context, spaces and line breaks in the wikitext may or may not affect the rendered page. Especially when editing templates, it is often difficult to see what effects whitespaces have. An extension of syntax highlighting could mark spaces and line breaks that affect formatting. For example ¶ for line breaks and · for spaces could be used, shown in subtle colors. In implementation, there would be a way to toggle the function on and off.

Prototype 2e: Update styling rules and color theme[edit]

Not all current colors are meeting accessibility standards, the two blues are not easily distinguishable, and when all colors combine it’s not always the easiest on the eyes. We completed a study on each of the colors, adjusting to meet contrast requirements for accessibility. The category colors would stay fundamentally the same - variables would stay orange and templates would stay purple - but small changes could improve the contrast, especially for people with color vision deficiencies. Colors would be adjusted for contrast and the background could be adjusted for optimum readability.

Feedback[edit]

We would like feedback from any users familiar with template syntax, whether you are comfortable writing it from scratch or if you only rarely use nested templates or edit templates. Please leave your feedback on the discussion page.

  • Would you find these changes helpful?
  • How would it impact your interactions with templates?
  • Which proposal are you most excited about?

Note: We appreciate all the comments received so far but also wanted to provide a way for quick responses and have added a quick survey to this section.

Note on the proposal of global Templates[edit]

The proposal of introducing global templates – templates stored centrally, that can be used in all Wikimedia wikis – popped up many times in the research conducted by the team, as well as while creating and announcing prototypes. We see the big potential of this proposal, but after looking into it we came to the conclusion that we don’t have the resources for this kind of a project. The WMDE Technical Wishes team is a small team and bound to a two year timeframe per focus area to ensure that we can make improvements in more areas of Wikipedia – our assessment concluded that this project would need more staff resources and time than we have. Therefore, we unfortunately won’t be able to tackle it at this time for now.

Prototype 3: Improve working with templates in Visual Editor[edit]

When filling out a newly added template or editing an existing template in Visual Editor, a dialog window pops up to add, edit, or remove different fields. The following proposals concern this window and how to more easily fill in the fields. This is often laborious and confusing for both new and experienced editors. It is difficult to understand what information to fill in to the fields and how to format it correctly. Most of the proposals aim to provide better help, while also assisting in the correct formatting of fields. To find this screen, edit an article in Visual Editor and click on “Insert” > “Template.”

Note: The dialog in the images is expanded to show the interface changes, but the lengthened size is not part of the design proposal.


Prototype 3.1 - 3.6 - Improve working with templates in Visual Editor

3.1 Better help text[edit]

Currently, the name of the template appears twice. In the proposal, the icon and title are changed to describe the section more clearly and guide you to the right place when you are looking for help. A rephrased sentence encourages you to visit the documentation page.

3.2 Required parameters[edit]

For added clarity, required parameters would be shown with a label instead of an asterisk. Tests have shown that asterisks do not universally mean “required” to users. Suggested and Optional parameters remain unlabeled.

3.3 Eliminate [[ ]] button[edit]

When a specific parameter is in focus, the [[]] button would no longer be shown. The [[]] button rarely serves a useful purpose and is being eliminated to limit confusion and simplify the interface.

3.4 Make instructions more visible[edit]

Currently, descriptions are hidden and only shown when the info “i” icon is clicked. Often these descriptions have critical information which helps you correctly fill out parameters and format them correctly. The proposed design removes the info icon and instead displays descriptions under the parameter name. When TemplateData is missing, then nothing is displayed (ex. Birth date). Currently, the info icon is visible but unclickable in these cases, which is very confusing.

3.5 Introducing grouped parameters[edit]

People writing TemplateData could choose to group parameters. This would result in a visible grouping in Visual Editor, plus sub-parameters would not have labels in bold. This would for example be particularly useful for image related parameters.

3.6 Drop down menu[edit]

Adds the possibility of specifying a list of values that are proposed for a parameter in TemplateData. In the template dialog in Visual Editor, they would be shown as a drop down menu from which you could select one or type in a different value. The field would have auto completion so that when you start typing, the proposed values are filtered.

Prototype 3.7 - Improve autocomplete selector

3.7 Improve autocomplete[edit]

Autocomplete would work for file names on Wikimedia Commons, in addition to the names of Wikipages and usernames. The current functionality would be expanded, so that if a parameter accepts these input types, then results would show once you start typing (see 7a). In addition, after a page is selected, it would be automatically formatted to become a wiki link (see 7b).

Prototype 3.8a - Add buttons to use existing Visual Editor media selector

3.8a Add buttons to use existing Visual Editor media selector[edit]

Buttons to add images or other files would be added to parameters of the corresponding type. You would no longer need to open Wikimedia Commons in a separate tab to search for an image. This would be particularly helpful for newcomers who might not know that they need to copy and paste a file name. When clicked, the buttons would open the existing Media selector for Visual Editor. Depending on which button is clicked, the corresponding tab in the Media selector would open.

Prototype 3.8b - Image preview

3.8b Image preview[edit]

After an image has been selected, the file name would be automatically inserted and a preview of the image is shown within the template dialog window.

Feedback[edit]

Proposed above are many smaller changes to improve working with templates in Visual Editor. What do you think about them and which do you think are (most) useful? Any type of feedback on the discussion page is appreciated. Additionally or alternatively you can fill out the quick survey in this section.

New Update for Prototype 1[edit]

In case you missed it: We posted a new update for prototype 1.

Based on the feedback we received on the foregoing, as well as all our previous investigations and discussions, we improved on the ideas and evaluated them as to

  • their impact (how beneficial are they?),
  • the effort required (how hard would they be to implement?), and
  • risks (are there negative side effects? might the project fail or be blocked by other teams?).

For those projects we deemed most valuable and doable for our team, we conducted further investigations, and developed more elaborate prototypes. The idea of a standalone Template finder, for instance, was dismissed; instead, ideas for better findability were integrated directly into the template editors. These high-fidelity prototypes were tested in usability tests with newcomers, casual editors, power users, template users and template creators & maintainers, to make sure our contributions would serve all types of users. We also made sure to have testers with diverse backgrounds (home wiki, including RTL wikis, age, gender, color blindness). The tests showed that some project ideas would create confusion or additional problems, or just wouldn’t help as much as we thought. Those ideas were dismissed or significantly revised. Other ideas generated a lot of excitement and were further improved by constructive feedback from the testers. Those are the ideas that will now be implemented.

Feedback[edit]

As always, feedback is very welcome. The best place for it is the talk page.