Making issue and merge request templates easier to use
Problem to solve
The current implementation of templates for e.g. issues and merge request within the industry is to prefill the textarea with the template text. This causes a variety of problems.
1. Scanning the template
There is no clear visual distinction between different types of content (heading, list, task), they are all purely text based which makes it tougher to find the aspect for are searching for quickly. The fact that all of it is markdown text makes it even more complex for novice users, as they will first have to understand and learn the syntax before filing their first issue.
Most templates are also quite long. To get an overview over the bug template for the GitLab Community Edition, the entire content is four times as long as the textarea itself, so the user has to scroll quite often and far if he wants to jump between different sections.
2. Quality of descriptions that get submitted Issues that get submitted without the necessary information is the number 1 issue that open source maintainers complained about in an open letter to GitHub.
A lot of projects suffer from users not complying with the template rules as there is no way to make fields mandatory, force users to write a minimum amount of characters or other techniques to increase the quality of the description in issues and merge requests. Instead, these rules are being added as pure text to the template , so when the user starts writing and still wants to keep the guidelines visible, having a mix of template guidelines and actually written text by himself makes it even tougher to get an overview at a glance.
These aspects cause a lot of descriptions getting submitted in a way that does not actually adhere to the rules of the project which causes trouble and extra work for the maintainers and everyone who wants to quickly understand what the issue or merge request is about.
3. Users submit template text
Users often do not delete the parts of the template that they don't fill out which causes the description to become longer than necessary and filled with content that does not help anybody understand the problem or potential solutions. It's not possible for the user to visually differentiate between actual content that the author wrote and parts of the template that he did not delete.
Example: In the GitLab Community Edition, the last part of the template is (If you can, link to the line of code that might be responsible for the problem)
. When searching for issues that include this line, you can see that more than 800 issues in total include this completely not helpful line.
Users looking at these issues see this content as normal part of the description. Long term users might be able to filter out this part more easily, but newer users will have to read it and understand that it's just a part of the template that got submitted with the rest of the actual content. This is time and mental effort from the user that's completely wasted.
Proposal
As @jareko mentioned, our descriptions are actually being used as forms. They give you sections to fill out, show hints for what information to include and offer checklists that you can use to make sure you have mentioned all necessary details.
We could offer administrators a way to structure a form in a yaml file, as recommended by @DouweM, and then render this for the user with individual input fields.
A very rough mockup could look like this. I have included different types of input fields, hints for how to fill out the fields and whether a field is optional.
This would make filling out the form easier, give more structure for the administrators which leads to better filled out issues and merge requests, and also solve our problem that we have a lot of duplicate data as all comments and hints would not get saved in each description, but only in the yaml file.