Good PMs write some kind of document to detail how to develop a feature. This gives the team a central place to know what has been said and decided regarding the feature. To be useful, this document needs to cover the most important details, and so commonly runs to a couple of pages. With several PMs writing quite a few such documents, this amounts to a lot of information.
Some teams go all-in on writing things down and get stuck and lost with all the resulting information. Some teams balk at the prospect and don’t write much down at all, with insights being lost and mistakes made. At Delibr, we believe that it is possible to get the best out of both worlds by working in a structured way, using a template as a starting point.
David Božjak, Tech Manager at Storytel, put it succinctly:
“My team at Storytel has been using Delibr’s feature refinement templates for several months now. There are too many benefits to enumerate all, but giving a consistent structure to our projects is key.
Now everyone in the organization, regardless of position, knows what to expect when they follow a project link and knows where the information relevant to them will be in the structure.
We no longer struggle with keeping our projects sufficiently documented, we always start with a template and then we insist we do all our work – even Jira – from the Delibr document, and the documentation is done automatically.”
Let’s break it down to (i) why a template helps, (ii) what template specifically to use, and (iii) what is required of a tool to make the most out of using a template.
The Magic of Using a Template
Every feature is different, and the details will vary. But over time, the documents often need to cover the same or similar topics. Therefore PMs will typically find their writing style over time, and converge on a format to use as a starting point.
This works well with 1 or 2 PMs in the organization. But, as the organization grows, so does the total number of people writing feature refinement documents. Without any effort or thought going into this, the result is likely that these documents will look quite different.
Generally, for any process that is repeated many times, variance can be problematic. Specifically, if every PM has their individual style of writing documents, this will lead to two problems:
- It will be much harder for the person who will read these documents to find the information they want if they all look different.
- If the PMs have not talked to each other to find a “best practice” for writing feature refinement documents, it is likely that variance between how they write these documents means that some PMs do it less well. This likely means that feature refinement quality is suffering as a result.
The solution to problems with variance is to standardize. A good way to do this is to agree on a template for all PMs to use as a starting point when writing feature refinement documents. To keep flexibility and avoid limiting the PMs in their work, it is important that the template is just that, a starting point.
Using a template as a starting point for writing feature refinement documents can yield three benefits:
- It can reduce “writer’s block”. If you have ever dealt with it, you know that this can be quite a hurdle. Templates can help with this. Rather than starting from a blank page, you will have something to look at and start with, helping you place your thoughts into a structure. This will speed up the writing process.
- It can make it easier for the team and stakeholders to navigate within the document and find what they are looking for. If a consistent structure is used across documents, the documents will be readable and easy to use for the whole product development team.
- It can ensure that the most important aspects of your features are covered. This, in turn, can increase the quality not only of the documents but the entire feature refinement process. Of course, this requires that your template actually covers the most important aspects.
Principles for Good Template UX
At Delibr, we have interviewed over 300 PMs about how they work with feature refinement. We found some principles that the best PMs use to write documents that help facilitate the conversation. Based on those, we developed what we believe is the best feature refinement document template to start with.
Some of the principles we found:
At the epic level. With a too big scope, the document tends to grow and become unwieldy and risk becoming obsolete. With a too narrow scope, it risks not properly capturing the reasoning for developing the feature. Normally a single user story is a too narrow scope, as it is often a combination of several user stories, an epic, that solves a user need. It all depends, but if forced to generalize, we’d say that an epic should comprise of 3-12 user stories, and last for 1-3 sprints. If an epic risks lasting more than a quarter, it is probably better to restructure it.
Both discovery and delivery. As we have written about before, it makes sense to spend time in a phase of feature discovery. Separating out discovery ensures that only features that make sense to do, i.e. that are valuable, usable, and feasible, go into development. The big risk with this is that discovery and delivery get too separated. It is surprisingly common that the actual feedback or data that led up to the feature being developed is not known to the developers implementing the feature. A good way to mitigate this is by using the same document for discovery and delivery. That way those who develop it can always just scroll up to see the problem statement as well as any recorded customer feedback or underlying data. (I know what you’re thinking, these documents could get massive. Don’t worry, we got a solution for this).
Structured for stakeholder readability. People will read the document in different ways. Executive stakeholders will read from the top and want a concise description of the problem, the solution, the success criteria, and the roll-out plan. The stakeholders that requested or are affected by the feature will also be interested in what user stories will be implemented. Specific functional stakeholders find it helpful to have a section of the document that speaks directly to them (e.g. QA, design, analytics, copywriting). And the team will go all the way, into the details of each user story and down to further details.
Focused on user stories. Stating the obvious here, but user stories are really useful. We found the main benefit of user stories (relative to “pure tech tasks”) is that they make it easier for non-tech people to understand what is being developed, and so enable better slicing decisions (i.e. decisions on feature scope). Because of this, we have found that documents centered around user stories are more effective. The way to make a document truly centered on user stories is to let the document evolve with the user stories.
- In the early stages of writing the document, the focus will be on clarifying the problem and sketching a rough picture of what the solution might look like. Then it will be enough to capture relevant user stories and write them down in the document.
- In the middle stages, the focus will be agreeing on the scope of the feature. Then the most important thing will be to prioritize which user stories to include, sorting them and moving some of them into a “later” subheading. To do this, it can be a good idea to do a user story mapping session [link] and then paste a photo from the whiteboard into the document.
- In the later stages, the focus will be figuring out more about how to fulfill the user stories in the first iteration. Then it is time to add more details under each user story heading, e.g. acceptance criteria and use cases as well as designs, copy, flow, and technical micro-decisions. If done properly, this can save time, in the transition to Jira.
Based on the above principles, we developed the “Epic Refinement Template” for our app:
But of course, the template is just a starting point. It should only be used as a base and be open to changes. Depending on the feature, it can be adapted with judgment, with headings and sections added, changed, moved, or removed. And working dynamically with the structure of a document is much easier using an outliner.
A Powerful Duo: the Template and the Outliner
An outliner is a type of document editor where the document is represented as a tree structure with bullets.
The screenshot above is an example of what document can look like in an outliner. It is possible to switch view and see the document like a “normal document” without indentation and with headings of a different font.
Working with a document in an outliner gives the editor more flexibility in engaging with the structure of the document, e.g. zooming into, collapsing, or moving around parts of it.
In combination with a template, an outliner brings three benefits
- First, by collapsing the document down, a reader can navigate among the headings of the template faster. A reader that is new to a document does not have to be overwhelmed by all its content but can dive directly into the parts relevant to them.
- Second, working from an overview of the headings in the document, it becomes simpler to add things to the right place. This makes it easier to adhere to the structure of the document.
- Third, changing the hierarchy of headings or adding new sections is effortless and does not risk messing up the whole document. This gives flexibility and reduces the risk of becoming too rigid in following the initial structure of the template.
Delibr is an outlining tool designed to make all of this easy. In addition, since it is made for Product Managers, it has an integration with Jira. The integration makes it possible to create and link Jira issues to parts of the tree structure, as shown below.
Taken together, this helps Storytel to create a shared understanding of the features they build in the whole organization. Are you interested in trying Delibr and see what it can do for your organization?