Agile Design Docs and Product Planning

Product Development | 2024-02-18. 8 min read (1835 words).

I really like light-weight technical design docs for creating just enough up-front technical design when needed. Similar concepts exist for product discovery and planning too. This is a quick intro to these concepts!

Topics:

Introduction

I have since long advocated for using light-weight design documents to investigate, document, and review small pieces of technical design right before implementing something technically complicated. This is used at Google and many other big tech companies and is a great way to combine thoughtful technical design with agile software development. I describe below what a design doc is and the typical way of working with them in agile teams.

When working with agile product management, similar challenges show up. In some cases, it’s enough to just use user stories (and epics) in addition with design docs to plan. I explore here what other light-weight artefacts can be created in a similar spirit to light-weight technical design docs.

Technical design docs

Design documents are great agile alternatives to the big-design-up-front (BDUF) from waterfall development. The idea here is to keep it light-weight (just enough design) and create new small design docs whenever needed rather than designing and planning far ahead from the start. The documents themselves can be created in Word or Google Docs or Markdown in Git. Templates can be used to make it easier to remember commonly useful information. However, the goal is to keep them relatively short and simple and only include what is needed. Typically, one design doc would be 2 - 15 pages.

This allows teams to strike a good balance between the two extremes of trying to design everything in detail before developing anything (BDUF) and never creating or discussing any technical design before implementation. By not creating the design earlier than needed, we avoid having to predict the future far ahead (which is nearly impossible) and can make use of everything we have learned so far. By creating a design document and iterating on it, we can reach a good design much quicker than if we iterated by writing software instead, so we avoid unnecessary rework. It usually gives us a better overview of the design too and makes it easier for others to review and understand it.

My standard recommendation is to then save these design docs for the future without keeping them up-to-date. This way, the historical explanation of why a certain design was chosen is easy to find for anyone wondering in the future.

I don’t have any good design docs that I can share publicly, except to some degree the post on building this blog using Hugo (here). I found a great website that summarises the concept with examples, however: DesignDocs.dev.

How to work with design docs in Scrum?

Agile software development with Scrum fits perfectly together with light-weight design docs, but it may not be obvious how. Here’s the way of working that I have usually recommended and seen work well. What is most important to realise is that it takes work both to create the design doc and implement it and this work is usually split up when planning.

The typical way of planning in Scrum is to have a backlog consisting primarily of user stories (and epics, which are bigger user stories). When a certain user story is hard to implement or estimate without a design document, we would typically split out an investigation task for creating and reviewing a design doc first and plan this into a sprint. Based on the design doc, we have more input for refining the rest of the user story for future planning.

These ‘investigation tasks’ can be called different things. Extreme programming has a related concept called a ‘spike’. I consider that the same thing. An investigation is not a user story, on the other hand. I sometimes suggest that we call it an enabler story and clarify in the description that it enables the estimation and development of the original user story. This can be illustrated in e.g. Jira by adding a label called ‘Enabler’, but just having different kinds of stories be the ‘Story’ type also works well. Recently, I would instead suggest calling these ‘discovery tasks’ (and let them be a ‘Task’ in e.g. Jira), which aligns with the increasingly popular terminology of distinguishing between discovery and delivery work in dual-track agile. I categorise design docs as discovery work. Let’s talk more about dual-track Scrum below.

In terms of planning, the design doc serves two purposes:

1. Enables cost/time estimation and tells us about technical feasibility.
2. Enables quicker delivery with higher quality if we decide to go ahead.

This means that we should plan a design doc task into the backlog before we need either of these. Sometimes, that’s right before delivery. Sometimes, we need to know about feasibility earlier, but delivery can then wait (once we know that it is feasible and approximately what it takes to deliver it later).

Dual-track Scrum

When working fully agile with product development, there are two kinds of work needed in parallel:

1. Discovery: explore what to build and refine the backlog.
2. Delivery: build what we believe is the right solution into quality software.

Both of these need to happen in small increments and during every Scrum sprint. My view is that both should also be planned into the backlog to some extent (not all work needs to go into a formal backlog). In other words, we need product backlog items (PBIs) that are related to both discovery and delivery. Ideas need to first go through discovery to then potentially be planned for delivery and feedback from both these types of activities should be used to refine our planning and iterate towards good customer and business outcomes.

The delivery part of Scrum is well known. The discovery side is often less well known, in my experience, and can be called different things. It is all about confronting risks up front and iterating on ‘requirements’ and ‘design’ (to use waterfall-style terms). Here follows a summary of the key concepts.

From DevOps Research and Assessment (DORA), we can see two primary capabilities related to discovery (with research behind):

1. Team experimentation
   • ‘For your organization to fully benefit from modern software development techniques, you must empower your teams to experiment with real users to achieve agreed-upon business outcomes.’
   • The idea is to give teams problems to solve and outcomes to achieve and let them iterate on both what solution to build and how to build it.
2. Customer feedback
   • For Scrum and agile to fully make sense, we need to act on feedback from customers. Getting customer feedback and acting on it is part of the discovery work.

Another framing of discovery work is that it is about managing what Marty Cagan calls the four big risks:

1. Value risk: will customers and users want to buy and use it?
2. Usability risk: will users be able to use it?
3. Feasibility risk: can we build it?
4. Business viability risk: will the solution work for our business (finance, compliance, ethics, etc)?

This is all good, but how is this done in practice? Concretely, there are many activities that can be done as part of discovery to handle the above: formal investigations, creating non-code prototypes, user testing, running experiments of all kinds, writing design docs, workshops, user story mapping, crafting a value proposition, talking to customers, analysing product and business metrics, A/B testing, creating customer personas, market research, etc.

The next section looks at some useful document types for this.

Product discovery documents

We have our technical design docs for dealing with feasibility risks. Similarly, it is probably quite clear what designers might produce to deal with usability risks. What documents can we create to deal with the remaining two risks above? These are related to product management. I believe similar light-weight documents to the technical design document can be useful here too, but I must admit that I have less experience of it. Additional documentation that is not directly used in planning and delivery are likely useful too (the same is true for technical documentation).

If we first look at traditional waterfall development, we often have detailed market requirements documents (MRD) and product requirements documents (PRD). This is similar to the software design document (SDD) that short design docs replace.

A first standard replacement for all this is the versatile user story and related epic (simply a big user story that needs to be broken into smaller stories for implementation). These are easy to underestimate. Two powerful aspects of user stories are that they focus on the value provided to a user and that they can be of almost any size and be flexibly split into smaller stories as needed (towards the top of the backlog). Writing user stories is an art that is well worth learning.

For discovery work or other non-user stories, either just use ’tasks’ in the backlog or create some kind of ‘discovery stories’ or ’enabler stories’. User stories are still useful for a large part of the work in a Scrum backlog.

When user stories (and related ‘discovery tasks’ and conversations) are not enough in themselves for planning work, these types of documents are worth exploring:

1. Product Opportunity Assessment as an alternative to MRDs.
   • Describes a small or medium-sized opportunity (or problem) and might trigger a product brief or design document as follow-up.
   • See svpg’s Assessing Product Opportunities.
   • This can be used to decide what ideas to invest in exploring more.
   • Similar to John Kotter’s first accelerator ‘urgency aligned around a big opportunity’ in Accelerate which recommends writing an opportunity statement.
2. Product Brief as a light-weight alternative to a PRD.
   • This describes a high-level solution (without going into implementation details). It can either be a text document and/or a high-fidelity prototype.
   • Here is a recommendation on product briefs.
   • I believe product briefs can be handled very similarly to technical design documents and maybe in some cases they could also be combined. If not combined, it can make sense for them to refer to each other. The Product Brief might require a design doc in order to know that the solution is feasible and get a cost estimate, for example. Either might also exist without the other in some cases.
3. PR/FAQ (or similar longer narrative) for big new opportunities.
   • This is based on Amazon’s working backwards method.
   • See descriptions at productstrategy.co and svpg.com.

To stay lean and agile, it is important to avoid creating unnecessary documentation. However, I believe these types of documents fit very well into agile product development, in a similar way to light-weight technical design documents and are valuable to make frequent use of!

Product vision and strategy

This is mostly out of scope for this post, but I also believe it is useful to document a product vision and strategy. svpg has examples of this too. OKRs are also often used to communicate strategic objectives. More on this another time!