One of the hardest parts of software development is communication and getting a team of people to all have the same context of what they are building, and why. There is a disconnect between design, business, and development. These roles have different priorities or understanding of problems, yet they come together to reach the same outcome.
That's why teams need a consistent method for sharing context. Context documents are sometimes called, briefs, initiatives, programmes, themes, recipes, or areas of work. They help get a product team on the same page about what they are trying to achieve. Context documentation is high-level and living documentation - instead, they inform about the wider context and link to the feature specification documentation.
The two methods for capture context are Briefs and PRFAQs. Templates for Briefs and PRFAQs are available below.
I was working in a small team of 6 and we were wrapping up the build of a new feature, about to deploy it into production. I was chatting with one of the developers about building this feature, and then he said, "Well, I know I spent a lot of time working on this feature, but I don't know why we are actually building this feature in the first place."
This showed me that throughout all of our design and development process, the context around decision making was always communicated verbally through meetings. This meant that there was no place to reference reasons for why we were doing this work. We needed to start focusing on documentation practices to build a better product.
The goal of context documentation for everyone to know:
why a Feature-set is important,
how a Feature compares to all other related Features,
what the underlying intentions for investing in that Feature are, and
what can be adjusted along the way.
Context needs to be communicated everyone. Things need to be visible always are:
what's being worked on,
why it's being worked on,
what decisions have been made,
what things are left to decide on, and
what research and validation is involved.
Documentation is still Agile
If your team is larger than 2-4 people, or you ever plan on growing larger than 2-4 people, you have to invest in the documentation. The agile manifesto says, "working software over comprehensive documentation." This means that documentation should still exist, but we should follow a practice of minimal valuable documentation. At the time that the manifesto was written, extensive documentation typically meant an extremely large business case, and full business analysis of all feature design before any development began. Briefs are a great way to capture relevant and core documentation on an as-needed basis.
I've heard too many reasons for not write things down. "Writing things down is not agile," or "All of the requirements are visible in the design," or "that it's not my job to write this down, you need to hire a business analyst for that," or "I can just have a conversation with the person to tell them what to do."
All of these statements prevent a team from scaling, prevent visibility, and force work and responsibility to be hidden and obfuscated.
Write it down and make it accessible
Large enterprises are slowed down by over documenting everything, many focus a large amount of effort on writing business cases and preliminary documentation that no one ever reads. Startups, on the other hand, have the ability to move faster because they have less paperwork, less communication overhead, and a higher tolerance for risk. One growing pain of product development during team growth from start-up to small to medium-size business is how to increase team productivity and not have communication channels slow the team down.
If it's not written down, did it even really happen?
You want to avoid a dangerous situation where one person holds too much important information in their head. And too much work is dependant on asking in-person questions to people.
Benefits of good documentation:
Shares knowledge across the team
Increases team scalability and productivity
Reduces the n+1 problem
Makes work visible
Create living documentation
Use feature development documentation to create living documentation that:
Can change with time.
Easily captures the changes.
Can be skimmed for an overview, and allows people to find detailed information.
Is accessible and readable, written in plain english.
Makes work visible.
Living documentation needs regular maintenance. Expect to put in regular hours a week keeping documentation up to date.
Method #1 - Product Briefs
Briefs are pages that hold the context for a theme, workstream, feature set, or team. They are top-level pages that get broken down into deliverable units of work.
Who owns the work: Product Manager, UX Designer
Involved: UI Designer, Business Development, Tech Lead
Briefs sit in a brief board, they are not prioritised in a list but are more of a wiki of all workstreams or themes relating to your product. The reason why briefs should not be managed in a kanban board is that Briefs may be partially in progress for extremely long periods of time - maybe even years.
What are Briefs:
Briefs are themes for the product. they get grouped together.
Briefs capture context.
They focus on outcomes.
They show status of delivery.
They link to all relevant history, data, and research.
What goes in a brief?
A brief is a theme to hold context and make searching through all of the documentation of your product easier. These are living documents, they get completed and updated over time.
Here is a template of everything that should be in a brief. I usually use the text below as the brief template every time we make a new one in our team.
🤖 Brief Template
Title the brief with a title that represents the best grouping of features for your product. Example titles could be Activity logs, Events, Goals, Journey Builder, Auth, etc.
Intro the Brief. Explain the problem, solution, and feature-set in two to three sentences. If a person is browsing through the product briefs, they should be able to know what to expect from the rest of this brief by just reading this overview.
Describe the problem faced by the actual users, and the context behind it. It can be useful to explain the problem from different perspectives - this problem may look different to different stakeholders. The goal here is to frame the problem from the user's point of view and how they experience the problem This can either be a problem statement or be a few paragraphs long.
Describe the value which a user will receive from the set of features outlined in this Brief. A value isn't 'I can now do X' - a value is 'I save time', 'I feel more confident', or 'it's now more straight-forward'. Different users may receive different values from the same feature.
Any research or known information that is used to validate decisions can be captured here. Briefly discuss what external validation you have about this problem being important to solve.
What's the current idea of how we're going to solve this problem? A visual representation is useful. It's understood that these designs will change as the team starts work on a feature - through spiking development, iterative design, or further user research.
Write outcomes as job stories
Job stories are a simple way to list jobs that a user is wanting to get done with this feature. Job stories focus on the outcome — this is important because our features briefs are outcome-oriented. Later during the design and backlog prep phase, you translate these outcomes into design and specs where we will focus on functionality.
Describe the solution and give an overview of what is being solved. Add videos, designs, or prototypes here.
This is usually a list to all of the Features Specs in this brief and where they are at organised into the delivery pipeline. This feature list is best displayed as a Kanban board to show where each feature is in the delivery pipeline.
Indicators and Success Criteria
List any relevant key performance indicators that are being tracked with deployed features. List the indicators that relate to this brief. (e.g. number of new users, churn rate, customer acquisition cost, number of open activities, engagement.) Use the list of indicators in the Feature Spec to help create success criteria.
For a wider context, it's sometimes useful to discuss the solution that you thought about, but discarded while you came up with the solution above.
Method #2 - Working backwards
An alternative way to capture context for the wider team is the working backward method. This is where you start with the final press release, and some questions and answers, then after everyone is in agreement, you begin the design and development after. Working backwards methodology is an alternative to writing briefs and used by many teams by Amazon.
What goes in a PRFAQ?
The PRFAQs are all captured in a wiki. They can be for anything really project, product, or feature of any size - big or small.
A PRFAQ is made up of three parts:
The press release, which is the public announcement.
A frequently asked questions list that is for public use.
A frequently asked questions list that is for internal use.
🤖 PRFAQ Template
What's the name of this press release? And will the target audience understand it.
No more than one sentence. What are the benefits? Who is the target market?
The summary is short, maybe 2 - 4 sentences. It should be able to be read by itself and still be understandable.
What is the problem that people face if your solution didn't exist?
What is your solution, and how does it solve the problem?
Quote from You
A quote from a spokesperson in your company.
How to Get Started
What are the steps that your end user needs to take to start using this feature or product?
Provide a quote of something that you expect a customer to say.
Closing and Call to Action
Tell the reader what they should do next. This could be downloading a product, or turning on the new feature, or completing a task.
Make a list of questions and answers that a customer or the general public would ask.
Make a list of questions and answers that anyone else in the company would ask.
Using both methods together
You can work with just Briefs, just PRFAQs, or both. It is possible to combine Briefs and PRFAQs together. You can use briefs to capture themes for delivery that relate to a single PRFAQ, or you can just use briefs, or just use PRAFQs for each feature set.