Author: Nils Janse

Feature Refinement Document for Product Managers

Not Writing a Feature Refinement Document Can Lead to Chaos

You probably know all about roadmaps and user story mapping in agile product management. Both are effective tools used to capture and communicate your product’s goals and the journey to achieve them. User story mapping, for instance, will help to prioritize among relevant features and user stories and give the development team a better understanding of what to focus on.

However, what neither roadmaps and user story maps have, are feature details. These are never detailed enough for the development team to understand what has to be done just by looking at either a product roadmap or its user story map. And they shouldn’t be too detailed. This is where the need for a separate feature refinement document comes into play. And for good reasons. 

The Three C’s in User Story Mapping

Before discussing the benefits of feature refinement documents, let’s have a look at some important aspects of user story mapping. According to Ron Jeffries, one of the creators of Extreme Programming (XP), and a signatory of the Agile Manifesto, user story maps have three critical aspects: Card, Conversation and Confirmation.


Card refers to the user story, as user stories are sometimes written on index cards The cards are not supposed to contain all the information about a feature, just enough text to identify it. It represents the feature and has notes on it that illustrate priority and cost. 


This refers to all communication among the stakeholders and the development team. Thoughts, opinions, and feelings are all part of the conversation. These are usually exchanged verbally, but could be recorded for future convenience. 


Confirmation refers to the set of acceptance tests that must be passed for the feature to be considered completed. An acceptance test is used to ensure the feature matches the customer requirements and has been implemented correctly.   

Feature Refinement Documents for Effective Conversation

The major chunk of the feature development journey falls between the Card (the starting point) and the Confirmation (the finish line). Feature refinement documents can make this journey run smoother, and here is why.

Coming back to Conversation, there are several communication channels that could capture it: whiteboards and presentations for live meetings, email, Slack, Jira (especially comments). However, it is usually not possible to have everyone updated on everything, as that would require everyone to be on the same communication channel at all times. People miss meetings, emails and messages. Sometimes missing the tiniest detail can lead to chaos.

The developers might not understand what is needed, the team communication might end up disrupted, and then the whole plan is delayed. Not the best situation, especially if the release date is getting closer. This is why a single document that contains all this information (in a well-organized, easy-to-navigate and readable format) is so useful.

When You Don’t Need a Document

There are two cases where there is no need for a feature refinement document in product management. One case is when everybody that will have an input in implementing the feature in question is present during the whole Conversation. In other words, they don’t need the updates and additional explanations, because they were present.

Another case is when there is a self-contained issue, such as clear-cut bugs or obvious design improvements. In all other cases a feature refinement document is useful to put the disconnected conversation back together.

Issues That Will Pop Out if You’re Not Using a Document

One of the possible issues to occur if you don’t use an agile feature refinement document are disconnected conversations. Going back to several communication channels mentioned above, it is often almost impossible to keep everyone updated and on track on different platforms at the same time. This is especially true when working with a large team. Disconnected conversations can lead to chaos, putting a halt to the development process.

Another issue that could do this is missed details. Neither backlogs nor user story maps or roadmaps can capture small details effectively. Backlogs often look overwhelming, while user story maps and roadmaps don’t cover all the small details about the features. In both cases the details can be difficult to navigate to, and to associate with the right feature. 

Pitfalls to Avoid

However, writing a feature refinement document is not a magic pill. There are pitfalls. The PM needs to capture lots of information. Yet that information is only useful if it is easy to access and navigate, which requires good structure. Sometimes, structuring the document properly requires more time than the PM has available. Then there is a risk that the document grows unwieldy and hard both to read and to work with.

When that happens, the agile document risks becoming obsolete, not used in practice. And having a document that nobody uses is as bad as not having a document at all. Sometimes it is worse even, as the time to create it has been wasted and people may not have realized that the document can not be relied upon.

Why Delibr?

Most teams already write some sort of feature refinement document. Writing it in Google Docs is the most common, which is better than not writing a document at all. But the teams that start writing these documents in Delibr find that they need to spend less time to get to a good structure. This is because Delibr is an outliner.

Delibr-product management software

Outliners were originally used for writing books and movie scripts. In an outliner, the whole document is represented by a bullets tree structure. This gives outliners two main benefits. First, choosing what to see by zooming into or collapsing parts of the document is much faster. It allows for both seeing the hierarchy of the whole document and focusing in on a small part. Second, all operations related to moving content around are much faster and require no formatting effort.

Maintaining the structure of feature refinement documents might seem unnecessary and time consuming for you as a PM. However, the results are worth it, especially if you use an outliner to be able to do it with much less time. As a PM, you can avoid chaos by being writing better feature refinement documents. We aim to make this less painful. Work smarter, not harder. 

Aged paper map

JIRA is in desperate need of refinement

An article by Jon Evans titled “JIRA is an antipattern” recently became the number 1 on Hacker News with 360 comments (and counting). The main point of the article is that JIRA is being used in the wrong way, and that product teams should complement its use by also writing documents. As indicated by the title of this article, although we agree with the main point, we would prefer to defuse the explosive original title somewhat.

For us at Delibr, this is of course very exciting, as the interest in the article shows how relevant the topic we are working on is. As we perceive the article to be so relevant, we decided to write a reply to it. It is written so that you can read the original article and our reply in any order.

Our reply:

We’ve just spent a year interviewing 200+ product owners about the problem that you are describing. For most teams, JIRA works great for monitoring progress on closely defined tasks, but context “above story level” is a real problem. The better teams do already use another tool than JIRA to write such documents, typically at “epic level”, and typically using Google Docs and/or Confluence.

But almost all struggle with writing this document, where common problems include:

  • duplication of work and manual updating between the document and JIRA
  • unclear handover of the source of truth, since things that are written in the document are “true until stated otherwise in JIRA or a JIRA comment.. or somewhere on Slack”
  • lots of input/questions/decisions from refinement meetings not captured in either the document or in JIRA

I think the solution is to think of this document less as a “requirements document” (many label this doc “PRD”), and more as a “refinement document”.

This “refinement document” should

  • try to capture the conversation that happens in refinement meetings
  • involve also the developers to cover not only “why” and “what”, but also a bit of “how”
  • evolve and be updated all the way through development as new insights are gained
  • be the source of truth and available to the developer working on the JIRA issue

We have made a tool specifically to support working this way with “refinement documents”. One dedicated place to refine features. Structure, collaborate, keep track of questions and capture not only decisions, but also conversations. Seamlessly transform your work into crystal clear Jira epics and stories. When you turn notes into Jira issues, you can see all the details via our Jira plugin. Happy to hear your thoughts, please do check it out at

POs should write explicit questions with decisions to structure the conversations around new features

This is the second article in a series on how the best Product Owners manage to get on top of their refinement process. The insights come from interviews and close collaboration with ~150 product owners from across tech.

A Product Owner is responsible for the 3Cs, Card – Conversation – Confirmation.

Most POs share the Card (story ticket in Jira) and the Confirmation (written acceptance criteria and/or attached reference designs) with their developers.

In an ideal world, the developers should also have been part of the Conversation, or at least the PO should have shared it with them, as that would provide them with relevant context, empowering them to make sound judgment calls and removing the PO as a bottleneck.

But oftentimes the developers have not been part of the whole Conversation. And in sharing it with the developers, the PO faces the problem that the Conversation does not naturally occur in a format that is easily digestible. The discussion that lead up to a decision is instead often spread out across many emails, chat threads, and meeting notes – if it is at all written down.

As long as this is the case, it is not feasible to share the Conversation, as it could take hours for a developer to go through it all, and even then, it might not be possible to extract sufficient context.

That is why many POs only share the Card and the Confirmation with their developers.

But the best POs make an effort to have a condensed representation of the state of the Conversation. In its most simple form, this is something that all POs should do. They should have one place for notes relating to each story, a shared living document or maybe an area on a wall.

Some POs attempt doing this by writing neat documents with formatted text in full paragraphs. But it is unnecessarily hard and time-consuming to try to capture the discussion and formulate the rationale for why a decision was made in that way. The result of this tends to be long and complicated sentences containing “based on”, “having considered”, “on the other hand”. This is a wholly unnecessary effort, as these sentences are not only hard to write, but also hard to read.

We believe that POs should instead use a bullet outlining tool, to structure the conversations around new features, and simply write down questions as bullets, with options as sub-bullets, and pros/cons below that. That way they can get maximum speed and simplicity by formatting neither text nor grammar.

Once they have that structure, they should be vigilant to continually capture and add whatever questions are raised that is related to that feature and also fill in different discussed options, pros, and cons – and of course decisions made. These should be added, not as full sentences and paragraphs, but as concise and to-the-point bullet points.

This way is not only faster to write, but putting the Conversation in this format also makes it much easier for the developer to digest.

The format is also easy to digest for the stakeholders, and so allows the PO to assign and follow up on specific input, (LATER: not to mention, it will also save the PO a lot of time in the end).

Delibr is an outlining tool for product owners that helps them handle the conversation around new features.

It aims to help POs bring structure and cohesion to a conversation that is often disjointed and split across email/chat/meetings by explicitly capturing questions with decisions.

Conversation is King, Product Owners Ignore This at Their Peril

This is the first article in a series on how the best Product Owners manage to get on top of their refinement process. The insights come from interviews and close collaboration with ~150 product owners from across the tech industry.

In Scrum, the PO’s responsibility is to manage the product backlog – to handle both prioritization and refinement of the items therein.

We believe the Three C’s framework by Ron Jeffries is a great way to describe the role of the PO:

  • Make sure the team works on the right things, typically expressed as stories, each written on a Card
  • Make sure the team and relevant stakeholders share enough understanding and agreement on what these stories mean, by facilitating a Conversation
  • Make sure this conversation is translated into concrete acceptance criteria and/or reference designs so that it is easy later to get Confirmation whether the story is done

The ideal scenario would be for the PO to get team and stakeholders in the same room, write the Card, have the Conversation and coming up with the Confirmation. However, in reality the Conversation happens in several iterations with different constellations of stakeholders and team.

And so most POs handle this by moving emphasis from Conversation to Confirmation. They add user stories to Jira (Card). Then they write acceptance criteria and attach reference designs to these (Confirmation). Often this works quite well.

Except it turns out that sometimes it is really hard to make sure everybody is on the same page, and so they become the bottleneck by virtue of being the only ones who were present when all conversations took place and so end up spending a lot of time handling additional meetings and back-and-forth communication.

Leading up to the interviews we let POs fill in a survey on how they work. One part of that survey focused on handling the Conversation and asked how often they experienced different types of problems.

It was clear to us, both from the survey, and from following interviews and collaboration, that these and adjacent problems cause a lot of lost time but also other issues relating to output quality and team happiness.

As we had further discussions with the survey respondents, we saw a pattern among the POs that expressed the least amount of these problems. They placed great emphasis on facilitating the Conversation. Specifically, we saw that they engaged in three practices:

  • They made an effort to keep a structured representation of the current state of the Conversation
  • They were diligent about asking stakeholders and team for specific input to the Conversation, and about following up on that input
  • They did not stop the Conversation when development began, but assumed new input would come up and so ensured continuity

By engaging in these practices, these POs managed to overcome the problems that other experiences. In the following articles, we will elaborate on these three practices. Next article in the series explains why product owners should write explicit questions to structure the conversations around new features.

Delibr is an outlining tool for product owners that helps them handle the conversation around new features.

It aims to help POs facilitate the conversation by enabling structure, follow-up, and continuity

Opinions are a wasted company resource!

We all have opinions. And when our opinions are not taken into account we felt not only personally ignored, but also that the company is missing out. But from the employers perspective, what is really an opinion. And when does it make sense to take it into account?

Taking an opinion into account has two potential benefits, insight and involvement. The benefit of the insight varies from basically zero to potentially very large, depending on what decision is being made, and how relevant the insight is. The involvement benefit of taking the opinion into account varies a bit less and depends mostly on how strong the opinion is, and to be frank, also on who holds the opinion. Not taking an opinion strongly held by a key team member into account can have quite a negative impact, and then the benefit of taking it into account is significant.

But taking an opinion into account also has a cost, mainly in the form of time and focus. To take an opinion into account, three things have to happen: it has to be captured, incorporated, and replayed. Capturing of opinions happen either from noting what someone states without being prompted, but often times it requires asking. Incorporating the opinion means thinking through, in a structured way, how it affects the decision being made. Once an opinion is incorporated, it can be replayed to the person who gave it. Replaying an opinion isn’t strictly necessary to take it into account, but without some kind of replay, most of the benefit from involvement goes to waste.

As you can see from this reasoning, taking opinions into account can really be seen as a cost/benefit calculation. So, if it is cumbersome enough to capture and incorporate opinions, it actually makes sense for a company to disregard many opinions. And that pretty much explains why most companies do.

But that then begs the question:

What if it was possible to reduce the cost of taking opinions into account?

That is precisely what we have been working on at Delibr. Our tool allows you to capture opinions in a structured format. It shows what people think, and based on what rationale, and makes it easy to get an overview of the discussion. Our mission is to reduce the friction that comes as more people are involved in making a decision.

As we have seen, if the cost of taking opinions into account were much lower, many more opinions would be taken into account, and that would give companies both better insights and more involvement.