The purpose of this page is to document best practices related to writing description templates for issues and merge requests.
Not all questions are applicable in all situations. The first step is to choose what topic the issue is about. Some example situations are a feature request, a bug report, and a UX problem. Don't create one issue template for everything, create a separate template for each situation.
An outline helps you organize information, ensures topics are covered, and helps you stay on-point. How to create an outline.
Informational hierarchy is important, but procedural hierarchy is equally important. The following template is suggested:
Below is an example that follows the above template:
Include the problem we're trying to solve. Insert here your request WITH reason Example: As an X, I want to do Y because Z.
You have to ask the right questions in order to gather the right information from the user.
Website request. What are you requesting? Do:
Request webpage update.
Insert answer hereand
list items below.
The 5 Ws are a basic tenet in information gathering and problem solving. Who, what, when, where, why, and sometimes how. Below are some example questions from each of the 5Ws.
Note that all questions can be asked in affirmative and negative directions (is / isn't, will / won't, etc). Generally speaking one is enough, but sometimes it's necessary to list both.
Example 1: Brandon will be building X.
Brandon won't be building Y. Chad will be building Y.
Example 2: Add feature X to section Y on all pages, except for page Z.
What do they want to achieve? What is the unexpected application behavior? What is the user unable to accomplish? What metrics allow us to measure that? What are the requirements?
Why do they want to do it? Why is this a problem? Why does the user need to do this? Why is this important to the company?
Where is this happening? Where do they expect it to happen? Where do we expect it to happen? Where are the users coming from? Where do they want to go?
Who is the intended audience? Who does this bug impact? Who is this a problem for? Who will be building this feature?
When is the right time in a user journey for this to happen? When will this appear on the website and when will it stay until? When is this valid? When is the requested due date?
When writing an issue template, it is often better to omit questions about "how". This lets the implementation team research solutions to propose.
Setup your templates to automatically add relevant information such labels. Set confidentiality if applicable. You might also want to assign issues automatically or add cc @ mentions to the template. For example,
/label ~"type::bug" ~reproduced ~needs-investigation /cc @project-manager /assign @qa-tester /due in 14 days /confidential
Before releasing a template, it's best practice to have it reviewed by both people who submit responses and people who review responses. Submitters will help you identify questions that need clarification. Reviewers will help you identify questions that won't provide data they need. Both will help you identify missing or unnecessary questions.
After you release a template, if someone isn't answering a question, it could be an indicator that:
If you're getting the wrong data, it could be an indicator that:
With each change you make to a template, document why you made that change so you don't make the same mistake repeatedly. Check to see if the change you made in one section is applicable to other sections. Review the other templates to see if they can benefit from this update too.