We organize our daily work with issues in our Linear workspace.
Issue format
A good issue needs to be precise. It should be very clear what is part of an issue, and what is not. If there are different expectations between the person who writes and who implements an issue, there will be rejects.
To this end, we use a consistent format for issues that looks like this:
Issue: Autocomplete
As a journalist, I want to have an autocomplete in the search bar, to have a more efficient way to find articles.
Acceptance criteria
===================
- When I enter 2 letters into the search bar on the desktop homepage, I get a popup with autocomplete suggestions.
- The suggestions are as determined by OpenSearch.
- When I keep typing, the suggestions change.
- When I erase my query, the popup disappears.
- The popup contains a maximum of 10 suggestions.
- When I click outside the popup, it disappears.
- If I click on a suggestion, I am taken to the search page as if I had entered the suggestion.
- The letters entered are highlighted in the suggestions.
- Design is here: <link>
Notes
=====
- The autocomplete on the mobile homepage is not part of this issue.
- At some time we will also show tags in the suggestion list.
The issue consists of a short introduction sentence, a list of acceptance criteria and (optionally) some additional notes.
The introduction sentence should include the role of the user, what the user wants and why.
The acceptance criteria are very verbose to the point of being too obvious. Everything that needs to happen is a bullet point. As a developer you can go through the list and make sure you didn't forget anything. You can be assured that nothing else is expected of you.
The notes can give you hints to future planned changes that you can consider when writing your code. They are just there to give you context.
Who writes the issue
To write an issue, one needs to know exactly what the client requires. Only the product owner or product manager can do that.
One also has to know the application, in order to foresee edge cases and difficulties that non-developers might forget.
If the project owner is also a developer, she can write the issue on her own. If the project manager is not a developer, she can prepare it, but needs to discuss it with a (lead) developer before it is ready.
The backlog
Every issue should begin its life in the icebox and only be moved to the backlog if it is ready to be worked on. The backlog should be a prioritized list of issues based on their urgency.
Estimates
We use estimates on issues to give developer a rough idea of how long it should take to implement an issue. Otherwise it might happen that a developer does something much too complicated, because he wasn't aware of some shortcut, or some feature that is already implemented.
We don't want very exact estimates, because they can easily start to frustrate a developer, if the issue turns out to be more complicated than anticipated.
We suggest a 0,1,2,3 point scale, with the following meaning:
- 0 points: <= 1h
- 1 points: <= half a day
- 2 points: <= a day
- 3 points: > a day
If an issue takes longer than 2-3 days, you need to split it.
