Write issues not user stories

At Linear, we don’t write user stories and think they’re an anti-pattern in product development. We write short and simple issues that describe the task in plain language instead.

The point of writing an issue is to communicate a task. It needs to be clear enough so that the assignee can perform it and also give enough context so that teammates who need to know understand what work is being done. So the goal when writing issues should be to do this as effectively and quickly as possible.

Why user stories are obsolete

User stories evolved over twenty years ago as a way to communicate what a customer wanted into product requirements that a software team could deliver. Fast forward to today and a lot of things have changed about how we build software. Customers are tech-savvy enough to articulate basic product requirements. We’ve developed standards for common features such as shopping carts, todo lists, and notifications so there is no need to explain how they should work. The best product and engineering teams understand their users deeply and are familiar with how their product should work.

User stories have become a cargo cult ritual that feels good but wastes a lot of resources and time. They’re a roundabout way to describe tasks, obscuring the work to be done. User stories are time-consuming to write and read and can silo engineers into a mechanical role where they code to the issue requirements instead of thinking about the user experience holistically at the product level. One reason user stories are complicated and difficult to scope is because they bring what should be product-level details into the task level. And frankly, they don’t match how we communicate about software in real conversations.

A better way to write issues

Write clear, simple issues that describe tasks in plain language. Write your own issues. Discuss the user experience at the product and feature level, not the task level. Instead of spending time creating user stories, spend it talking to users and thinking through features before building them.

Describe concrete tasks or problems

An issue should describe a task with a clear, defined outcome. This could be a piece of code, design, document, or action to be taken. If it’s not a task, then it doesn’t belong in the issue tracker. Maybe it’s a project idea that needs to be fleshed out in a document or conversation or a larger feature that should be broken down into smaller, tangible pieces of work.

There will be exceptions to this rule. For example, before working on a feature you’ll spend time exploring the design and technical approach. You can create placeholder issues in these instances to break down later (e.g. Explore design) or frame it as a deliverable (e.g. Write project spec).

Write clearly and directly

Write short and simple issue titles that directly state what the task is. The title should be easy to scan, since most people will read it on a list or board in the context of other issues. Descriptions should be optional–not required–and can include relevant thoughts or context as well as links to deeper discussions. Write only as much as you need to share to perform the task and communicate relevant information to the team.

When sharing a feature request or bug report, quote user feedback directly instead of summarizing it. Often, a customer describes the pain point more authentically than you could summarize it and it’s faster to copy and paste, too. Link to the customer conversation so that if more information is needed, it’s easy to get.

Write your own issues

Everyone on the team should write their own issues. It’s faster and easier for the person who understands how to do the work to write issues describing it. It also sets up your team to do a better job. When you write your own issues, it forces you to think through the problem at a deep level. This creates space to come up with even better approaches and makes it easier to spot shortcuts or missing parts in the plan. The practice also reframes how you approach work entirely. Instead of building to mark a task done or check off a list of requirements, your focus is on the product or project deliverable.

In some cases, it makes more sense to write issues for others such as when filing a bug report. This should be encouraged with the caveat that issues are written slightly differently. When writing the issue, frame it as an ask or describe the problem. Let the assignee come up with the solution and then rewrite the issue as a task.

Keep user experience discussions at the product level

Discuss the customer experience at the product level when you spec out projects and build your roadmap. Engage the full team in these conversations–designers, engineers, and customer-facing folks–so that everyone has a deep understanding of the user needs, limitations, and product requirements. Then delegate the work to project teams and expect them to deliver. They’ll understand the user experience intuitively, so you don’t need to clarify it at the task level.