Summary: The most important bit when summarising the problem, is it’s impact on the business.
Problem: We cannot reliably provide old statements to retailers.
Impact: Our partners are frustrated. The team is wasting time to retrieve the statements. Our accounting becomes a painful process.
Measure of Success: Success is at 0 tickets/emails requesting old statements.
Focus on the affected stakeholders and try to quantify the actual impact: If I change this, I should see this. It’s key to be able to measure the impact a change will bring. This may be with specific metrics (e.g: 20% increase in sales) or implicit gains (e.g: customer support will be sleeping better at night). As long as the impact is defined beforehand, we can validate through quantitative or qualitative evidence if we were successful!
Remember at the end of the day, changes and features are built from people to people — never forget the human element.
Details aka. “Why does this happen?”
Ask “why?” five times to get to a root clause. Assume that others are not that familiar with the topic, so start from the root when explaining! Also this ensures we are solving the right problem.
Describe the current solution here. Find what’s already out there, what kind of workarounds do people do at the moment?
To refund a customer, the team is currently doing a manual change in admin, then going to the payment provider to do the refund manually, then return back to admin to record the change.
Ideal scenario aka. Story mapping
Describe the user flow from the user’s perspective. Follow the BDD style.
- As a user I should be able to login to use my account.
- As a retailer I should be able to set an item out of stock to keep the information up to date.
Constraints and needs
List the problems (can be technical, business etc.) you have to keep in mind. And list the criteria you can use to evaluate the proposed work.
Some common constraints could be: legacy, modularity, backwards compatibility, future proofing, race conditions, dependency on third parties.
- Creating an order should never fail, even if a shipping provider is down (Decoupling)
- The solution should be sensible. Keep in mind that emails are not sent over secured channels and can be compromised (Security)
Change aka. the proposed work
After you described the current scenario and painted the ideal one you need to figure out how can we get there.
This might also mean that first we have to figure out the:
Almost every project has unknowns. A good rule of thumb is to tackle these first. Not just so you can know for sure that we can do it. But also because an unknown can mean that our estimates are completely off when it turns out to be a much bigger thing than we first thought.
You can have multiple alternative solutions, but order them from low effort to high effort. Try to show some examples for comparison of efforts.
This is probably out of scope for this document, but it’s a good idea to link it here.
The steps to get things live. Generally would part of the spec. Don’t worry too much about it in the beginning, but highlight it, if it’s requires more than the usual effort.
After implementing the change, you may highlight it here what got left out that should be done in the future.
Keep in mind there are no good or bad answers for many of these, but you should be able to answer to all of these:
- On what level, and how detailed I want to describe things?
- Did I write details into unrelated sections?
- Who is this document for? Do they really know all that stuff I assume?
- What impact would this change have on the business?
- Can we quantify it?
- How do we measure that the change solved the problem? How does winning look like? (ROI, proof of impact)
- What is the root cause? (“Why? Why? Why? Why? Why?”) Are we solving the right problem?
- Can we break up the solution into smaller chunks to reach the goal faster?
- Are we trying to solve a general problem before something specific?
- How do people solve this already?
- Did we talk to them yet?
- What’s the ideal scenario?
- What problems will the implementer face?
- Is this going to be used in 3 month down?
- Would this break anything? Is it backwards compatible?
- Could the users work around the proposed solution for edge cases? Do we want to allow that?
- How are we going to roll it out without affecting other systems?
- What are the unknowns? How can we figure out them ASAP?
Products are made through conversations. Typically, either due to business requirements or because of a growing pain, someone decides that there is a need for a change. The change is then discussed with a few people to validate that this change is really a good idea and should be put forward. That plan is summarised in a couple of pages and shared for further discussion.
This document aims to be a guide on how write that plan, to achieve good discussion and ultimately it’s goals.✌
Level of detail
Start out small and share it early, as time goes by the document gets more and more detailed. Sharing the document while it’s work in progress makes it easier for you to gather feedback early on and also makes it easier for others to feel like they own a piece of it. Think of your proposal as a document that matures over time, early comments are invaluable to ensure you’re tackling the problem in its entirety and from the right direction.
By the time it’s ready to implement, it might even get split into several implementation plans. It’s very important though to ABC (Always Be Capturing) so you and your team can come back to what was agreed before. It’s especially nice how you can share it with new joiners to quickly get them up to speed.
Whenever you write a proposal keep in mind that it will go through many steps and to communicate your intent accordingly with the right context and people in mind. 🐸 🐴 👾
Whatever your work is, it’s important to realise it’s part of a bigger process, perhaps such as:
- Identifying an issue for improvement
- Discussing the issue with key stakeholders
- Coming up with possible solutions
- Breaking it down to actionable chunks and communicating it to the team
- Rolling your solution out on production
- Measuring impact