Writing Agile User Stories for a Small Startup.

Thoughts and Experiences Writing Stories on Small Developer Teams.


Brooklin Myers

3 years ago | 4 min read

Thoughts and Experiences Writing Stories on Small Developer Teams.

Understanding User Stories and Agile Development.

A user story is a description of a task or feature requirement. User stories are sometimes called cards, tasks, tickets, stories, features, and more. User stories are commonly used on Agile software development teams. Agile teams focus on frequent and immediate deliverable chunks of value.

If you don’t already understand what an Agile team is, it may help contrast them against Waterfall development. For example, while Agile teams focus on small and immediate deliverables, Waterfall teams focus on front-loading planning.

Certain routines are often associated with Agile Teams, Though Agile Development is not merely a collection of practices. Instead, it’s a mindset of continuous iteration and improvement. These routines Include kanban boards, weekly sprints, user stories, standups, and more.

To understand user stories, you need to understand kanban boards. Kanban boards organize tasks similar to a to-do list. Tasks will flow through different states depending on the team's needs. Common states may be Backlog, In Progress, Ready for Review, and Done.

Here’s an example of a Kanban Board using a common tool called Trello.

How to Write a User Story.

I have opinions on how to write user stories that I’ll share, but more importantly, write stories that work for your team. Do not follow the recommendations of another developer or team simply because it works for them. Instead, find what works for you and your team.

The software industry has plenty of opinions about writing stories that effectively communicate the requirements for the feature.

You can stick to a strict format, something like:

  • as a user roleI can actionso that benefit

Alternatively, you can write more technical dev-focused titles.

  • Add a CSS Preprocessor.
  • Fix broken NPM audit packages.
  • Speed up Slow User Notes API Call.

Sometimes you may have stories with open-ended goals, especially with research tasks.

  • Explore options for UI Frameworks
  • Explore options for SEO optimization

Often I see people saying that there is one right way. I don’t think so. I think all of these are perfectly suitable depending on the context.

Types of Stories

Before writing, I lacked terms for describing types of user stories. I found the terms User-Focused Stories, Non-User Stories, and Spikes. Terms are just terms, but these fit my intuitive understanding of types of stories so I’m going to stick to them.

User-Focused Stories.

Focus on benefits rather than the developer implementation. These types of stories often lend themselves to the format:

  • as a userrole I can action so that benefit .

Non-User Stories.

Focus on the developer implementation or software needs. These stories tend to lend themselves to a shorter developer-focused format. If you start the story with “As a Developer,” you are probably writing a Non-User story. In my experience, Non-User stories often lend themselves to a to-the-point description rather than a strict format.

If you’re on a team that forces you to stick to the format, feel free to write:

As a Developer, I can stick to a dogmatic format so that I can make management happy and build my damn feature already.

However, you may also need to follow that with a resignation so consider ignoring my advice here 😆


Spikes focus on exploring knowledge. Often Spikes don’t have a clear outcome other than determining how the team should move forward. This might be researching how to be compliant with industry regulations or researching options for technical solutions.

How to write good user stories.

Warning! Dogma Ahead!
Warning! Dogma Ahead!

A user story exists to convey information to the person handling the desired task. They do not exist to follow a dogmatic format or replace communication. You have to choose the format that works for your team, but I do have some goals that I think any format should try to address.

A Story Should not Overcommunicate or Under-Communicate.

Organizational types tend to prefer structured communication and often want to add more and more detail to stories. However, in my experience, the desire to formalize the process leads to additional overhead and no benefits.

However, if a story lacks basic information, that’s a problem. For example, “improve styles” is probably an unhelpful story unless your team collectively understands what that means.

A Story Does not Replace Communication.

You cannot replace communication no matter how much information you put in your user story. You cannot answer all potential questions, and you will not save time by trying. Embrace the need to communicate stories.

User stories will never replace communication on your team. If you have questions, you’ll need to talk.

A Story Should be Descriptive, not Prescriptive.

A good story focuses on the why not the how. They focus on the goal, not the means. This is true even for a technically focused story. For example, if the goal is “reduce the page load time,” but the story says “reduce image size,” it narrows the developer's focus and restricts their ability to be creative and clever with their solution.

That said, providing recommendations in the story is perfectly fine and helpful. Just try to be careful of forcing the developer down a path.

A Story Should be Quick to Write.

On small teams, stories should be quick to write. Large teams may have different organizational requirements, but small teams are supposed to be lightweight and fast— that’s their competitive advantage.

If you have an overly formal process for writing stories, consider how to streamline.

A Picture is worth a thousand words.

“Fix Typo” is a terrific user story if a matching picture with the typo accompanies it. Putting pictures into your story often communicates far more than an intensive list of requirements. Not every story needs a picture, but if a story lends itself to a picture, add it.

Final Thoughts

A user story is good if it works for your team. The purpose of Agile methodology isn’t to adopt specific practices but to focus on what works for you. So while I’m reasonably confident about the goals of a good user story, the specific means and format should be for what works on your team.

A 24-hour hack project will have different stories compared to a 20-year-old software company. So there is no one right answer.

Pick the answer that works for your team.


Created by

Brooklin Myers

Content Creator @CodeCastApp Elixir/Phoenix Developer at Aplicar. Lover of JavaScript Slayer of dragons Sharing what I learn!







Related Articles