Skip to main content

Agile Product Management in Roam - Part 1

Agile Mona Lisa

I spent the last week working on a Roam template for Agile Product Management. My goal is to create a step by step how-to guide and a full-featured template database, that a product development team can pick up to kick-start their process using Roam. I assume that Roam will be the only task and user story management tool used by this team, and I am developing a fully self-sustained solution built 100% around Roam's capabilities.

I wanted to deliver something practical, something that you can pick up with confidence and use. For this reason, I started with a blank database and use Roam to create this template organized like a mini Agile project. I am building the plane while flying it. My graph is public; I encourage you to look around. Read my user stories, check out my product backlog, look at sprint plans, personas, templates, roam/css style sheets, naming conventions, etc. Start here by accessing the Product Vision page.

This post will give you a quick rundown of Agile Scrum and my hands-on experience using Roam as my Agile Product Management tool for developing this template.

Keeping to the ethos of Agile Product Development, view this post as the first sprint demo of the Roam Agile Template. I hope to show you the Minimum Viable Product I've developed.

Agile Product Management vs. Traditional Project Management

Oversimplifying it, there are two ways to deliver a product. One is not better than the other, only more suited for certain situations.

  • Develop a detailed requirements specification, craft a design, plan the implementation, then execute the plan;
  • Or build a highly competent and committed team, make sure they understand who will use the product and how, give them resources and, let them deliver a working minimum version of the product as quickly as possible. Then keep improving on the product in an ongoing process of product releases fueled by customer feedback.

I assume you are familiar with the concept of both. I will summarize my understanding not so much to explain a new concept to you, but to share with you my understanding so you have a better picture of what you can expect in the Roam template.

Traditional project management is also known as the waterfall approach. The name is a reference to how the project plan looks on paper. Each phase of delivery is like a step in a cascading waterfall: scoping, requirements specification, detailed design, implementation, testing, and go-live.

cascading waterfall - the traditional project approach

Strict controls are at the center of Waterfall Project Management. The project manager has a carefully developed plan and budget for implementation. Delivery of the project is about ensuring everything happens in line with the plan.

Traditional Waterfall Product Development

Agile takes a different path. Instead of detailed specifications and designs, the focus is on storytelling. Understanding how the user will use the product and delivering small increments of working solutions that the end customer can immediately use. Agile works based on the understanding that often when you ask someone what they want, they will list requirements, most of which they will never need. We are not very good at conceptually understanding what and how we will use in practice. We need to get our hands on it.

Agile Product Development

Agile is not an incremental implementation of a Waterfall project plan. In Agile Product Management you ship a Minimum Viable Product (MVP) as early as possible (the pencil drawing of Mona Lisa), then you refine it through iterations and with feedback from your customers.

Agile Mona Lisa

Agile in a nutshell

Agile Manifesto

Agile builds on the foundation of four key values:

  • Individuals and interactions over processes and tools.
  • Working software over comprehensive documentation.
  • Customer collaboration over contract negotiation.
  • Responding to change over following a plan.

There is value in the items on the right, but often there is more value in items on the left.

In some situations, the traditional approach is better. For example when environmental or safety concerns outweigh the desire for agility (e.g. building a refinery), or in the case of “assembly line” type projects when you deliver the same product with only slight modifications (e.g. building family houses, deploying accounting software, etc.).

Built on the four key values, the Agile Manifesto asserts 12 principles. Since this post is not a detailed agile walkthrough, I will just quote these in "keywords". If you are interested, Google is your friend, research the subject.

  • Customer satisfaction through early and continuous product delivery.
  • Welcome changing requirements and accommodate them through the development process.
  • Frequent delivery of working product.
  • Continuous collaboration between the "Business" and the "Developers".
  • Support, trust, and motivation.
  • Face-to-face and co-located teams.
  • Working software as the primary measure of progress.
  • Sustainable development by maintaining a constant pace of delivery.
  • Attention to technical excellence and good design.
  • Simplicity.
  • Self-organizing teams.
  • Regular reflections on becoming more effective.

The focus in agile is on collaboration and storytelling, not on building comprehensive documentations. Storytelling by nature is messy. Details that apply to other parts of the story will emerge in the most unexpected situations. We need a tool that is flexible, and able to accommodate this free-flowing nature of stories. This is one aspect where Roam easily beats any of the Agile Development Frameworks on the Market.

There are many ways to be agile

Since the Agile Manifesto was written twenty years ago in February 2001, people have found an uncountable number of ways to be agile. The template I am developing in Roam follows the Scrum approach. You can find Scrum to the left of the big blue circle on the image below.

Deloitte - The Agile Landscape v3

My disaster story with Agile

My first Agile project was a complete disaster. We got ourselves a shiny Agile development environment, set up our sprints in the system, listed our user stories in the product backlog, and then engaged in authoring detailed specifications under the disguise of backlog grooming. We were running an Agile project following the Waterfall paradigm. Our first sprint took 3 months and only delivered documentation. We kept postponing the sprint demo to have something we can show our customers. Our second sprint was shorter, only two months, but not because we improved, but because after five months they ditched the project... which was an improvement in its own way. After five months of work, we still didn't have a working product, only documentation.

I learned two things through this experience.

  1. Agile requires a completely different mindset. If you have a team trained and socialized in traditional projects, you need to invest the time in training the team to be agile. The best is to bring in an Agile coach who stays with the team until they get in the rhythm of things, at least the first 5 to 10 sprints.

  2. While Scrum looks simple, free-flowing, and straightforward, there are some basic rules you need to stick to consistently. You should religiously stick to Agile Ceremonies, especially while the team is still young and adapting to Agile.

Ceremonies, artifacts, and roles in Scrum

There are five Scrum ceremonies (sometimes also called events), these are backlog grooming, sprint planning, daily standup, sprint demo, and sprint retrospective.

The three artifacts are product backlog, sprint backlog, and a potentially releasable product increment.

A Scrum team typically comprises seven to nine people, one product owner, one scrum master, and the development team.

Sprints should be short, typically one to four weeks long. Each sprint aiming to deliver a working product increment.

In an agile project, the scrum master is the master of ceremony. She/he is responsible to organize meetings, remove roadblocks, and maintain the rhythm of work for the team.

The team tracks future development work on the backlog. The backlog is a list of user stories, each describing a feature of the product from the user’s perspective. The product owner ranks the backlog based on importance and value. The product owner is the story-teller. His/her role is to explain to the developers how and why end-users will use the product.

The team works in sprints. At the beginning of each sprint, they pick stories from the top of the backlog, stories that are ready based on the completeness of the user story. They place these stories on the sprint plan and track their delivery typically on a kanban board.

Sprint Plan kanban board

During the sprint, the developers and the scrum master meet for fifteen minutes every day where they discuss what each of them has achieved during the previous day, what they are working on that day, and if they need help with anything.

Daily Standup

A few times during the sprint, the developers will get together with the product owner to discuss requirements for future sprints and future user stories. These are the backlog grooming sessions that play an important role in building a strong understanding of the requirements within the team.

At the end of each sprint, the team shows their solution to the product owner and to other stakeholders. During these demonstrations, the product owner verifies stories against the acceptance criteria and accepts or rejects them. Once the sprint is closed, the increment may get released to end-users (think of the frequent app updates on your phone), and the team meets for a retrospective discussion where they discuss what went well and what they want to improve for the next sprint.

Sprint Retrospective

Let's look at this process in the Roam Template Prototype I am building.

Agile in Roam

Most of the articles about Agile talk about the sprints, user stories, and how you work through iterations, but omit a discussion of the beginning. Where do you start? How do you get the agile cycle going?

Sprint 1

I started with an empty Graph by creating a page for the [[Backlog]] and dumping a list of ideas on the page as page-links to future user stories. I made a design decision (fueled by earlier thinking about managing a growing number of pages and tags in Roam) to place every artifact in its dedicated namespace. This helps with search and organization. I first placed stories in the stories/ namespace. I later revisited this decision and moved all my stories to the story/ namespace for sake of naming consistency, when I settled to use words in their singular form for namespaces.

Product Backlog

At first, I had little structure, just a flat bullet point list of things I felt I needed to get done. Once I had the list, I ranked items by moving blocks around using ALT+SHIFT UP & DOWN.

I thought I would create the template in a week (what was I thinking!!). To give me ample hands-on experience with using the template in a real-life setting, I decided on one-day sprints. I named my sprints “sprint/Day 1”, “sprint/Day 2”, but later renamed them to just “sprint/1”, “sprint/2” when I realized I bit off more than I can chew next to daily work. This project is small, there is really no need to define epics, but to experience what it would be like to run a larger project in Roam, I also defined epics.

I added a checkbox {{[[TODO]]}} to all my epics, sprints, and stories on the backlog, to allow for page filtering. When I am done with a sprint, during the sprint demo, I tick the checkbox for accepted stories on the backlog. This way I can easily filter out completed items from the page, resulting in a much cleaner look.

Backlog filtered

My first user story on the list was to create templates. I wanted to create these early on, so I can start using them to gain first-hand experience on how they work. Also, since I have sufficient practical experience with Agile projects, I felt confident that I know what templates I will need.

I will use the native [[roam/templates]] until I hit a blocker and then implement more complex templates using Roam42 SmartBlocks. My first templates were [[User Story]], [[Sprint]], and [[Standup]]. The others came slightly later.

Roam Templates

I continued by writing an initial version of a [[How To]] guide and a list of design [[Dilemmas]]. This helped me think through how I was going to use Roam for managing my agile product development process. Later I created the user story [[story/Document final how-to guide]] to update the How To guide. Any time I make a comment regarding use of the template, be it in a user story or elsewhere in the graph, I tag it with this story. As a result, I have all the reminders of how-to design decisions as linked references at the bottom of this user story waiting for me when I get there with my work.

I finished sprint one by publishing a short YouTube video of my graph to Twitter.

Sprint 2

I started sprint two by writing sample user stories. In a normal Agile project, this activity would be part of backlog grooming. Since I am developing the Agile Template for Roam, I added this as a story. My purpose here was to experiment with the user story template, and with the use of Algorithms of Thought (AoT), not just to improve the quality of stories.

Writing user stories has led me to two groups of learnings.

First, I found the use of different AoTs very helpful.

Second, I realized that my assumption that the [[Backlog]] will be the primary location where user stories are born was wrong. As I was writing stories, extending the how-to guide, and working through design dilemmas, each time I had an idea, I created a new user story on the spot. This is actually one area where Roam really shines, your ability to preserve information in context. Creating the user story in the context where it came up, will allow me later, during backlog grooming, to see linked references of a story, and to better understand where the story is coming from.

Linked References

However, this also raised a problem. How will I know which stories are missing from the backlog? Luckily, Roam is more than just a note-taking application. As you can see on the screenshot below, you can craft a Datalog query to identify stories in the graph, but missing from the backlog. Once I had the draft query ready, I created a user story [[story/Create SB to copy missing stories onto Backlog]] to move this query logic into a Roam42 SmartButton. It is on the sprint plan for [[sprint/3]].

Stories missing from the backlog

Closing thoughts

The template is not yet fully ready, however; I encourage you to check out RoamAgile and contact me here on the blog, or on Twitter, or by email to share your thoughts and inputs. Poke around, read the product vision, check out the query to pull active stories on my developer page [[Zsolt]], look at the [[roam/css]] templates, play with the sentiment analysis SB I included for processing customer feedback in [[story/Customer Feedback SmartBlock with dialog feedback type]], etc. There is a lot to explore and still a lot that needs doing.

I will continue to work on the template, hoping to release version 1, including a YouTube walkthrough and a downloadable empty EDN file for you to try out in your own projects.

Check out my related posts

Like this post?
Show your support.


  1. Hi Zsolt,

    I've been interested in your workflow Agile.

    But I have a problem:

    In my situation, I have multiple projects I need to handle at once.

    This means that I don't have, for example, `sprint/1` but rather, `projectA/sprint/1`. How would you go about solving this.

    Also, is it a bad idea to use `projectA/Sprint1/standup` as my page name?

    1. It should not be difficult to change, I've been also thinking about this needing to be done. If you are familiar with Javascript you should be able to work it out... but I'll try to find the time in the coming days to take a look at well.

      I don't know your situation, so it's hard too comment on the standup question. Your suggestion could work... I can see the logic behind it.


Post a Comment

Popular posts from this blog

Showcasing Excalidraw

Conor ( @Conaw ) pointed me to Excalidraw last week, and I was blown away by the tool and especially about the opportunities it opens up for  Roam Research ! It is a full-featured, embeddable sketching component ready for web integration. This post will showcase key Excalidraw features and discusses some of the issues I still need to solve to complete its integration into Roam. I spent most of my free time during the week integrating Excalidraw into Roam. This article will introduce Excalidraw by showcasing its features.

Mind mapping with Excalidraw in Obsidian

Mind-mapping is a powerful tool. In this post I will show you how and when I mindmap with Excalidraw in Obsidian and why mindmapping is such a good tool for Personal Knowledge Management. Like this post? Show your support.

Evergreen Note on Note-taking Strategies and Their Practical Implementations

This is an evergreen note that I will be revisit regularly to develop a comprehensive list of note-taking approaches including their practical implementations in various software tools. This post will serve as an elaborate table of contents, including a brief introductory discussion on the importance of note-taking, followed by a high-level walkthrough of each method. Links to posts and videos with detailed examples and descriptions will follow over the coming weeks and months.

Deep Dive Into Roam's Data Structure - Why Roam is Much More Than a Note Taking App

Which are the longest paragraphs in your graph? Which pages did you edit or create last week? How many paragraphs of text do you have in your database in total? Which pages do you have under a given namesapece (e.g. meetings/)?