How can specific product decisions be documented?

If there is a common document type where you can keep track of your decisions regarding features over time, that would be interesting to know. I’m not talking about how you direct developers; rather, I’m referring to how you articulate to other parties why you made a decision (which is typically a combination of practicality, strategy, user information, analytics data, thought evolution, and other things).

In order to keep track of this thinking over time and recall what happened a few months later and where the thinking ended up, I just sort of made up the phrase “design rationale,” although it comes to me that it might be “named” something! I’d be interested in knowing how you handle situations like these in other countries.

12 Likes

Add decisions as comments or modifications to the actual narrative after it is in Jira. After that, it is effectively searchable & timestamped. Additionally, if you need to track the development or history of your product, check that the tales contain the right labels or other identifying elements.

11 Likes

Or use Productboard and track at the product level (more digestible to stakeholders) and dive into Jira if needed for technical details.

11 Likes

Yeah, and using the roadmap feature you can easily access tickets in certain time periods

10 Likes

We document the requirements for the functionality on Confluence and then add to it. We place a change log at the top and a decision matrix in a table with plenty of visibility if there is client feedback.

If there are numerous changes that must be made at once, a new project will use the previous version as a guide.

9 Likes

In all honesty, I don’t, the majority of the time. Every day, we make a lot of decisions, and it takes time to record them for history. Who actually reads old documents that explain why teams took specific decisions? Big decisions, yes. Small decisions, no.

8 Likes

I refer to it as a “decision doc,” and I only use it for significant issues. The decision doc is a tool to think clearly, focus discussion on sub-items, and monitor when each discussion is resolved. It is NOT a technique to retrospectively chronicle what transpired. Then it serves as future documentation. I make it clear to all of my PMs that I want to see them develop strong PRDs, go/no-gos, and decision documents. In my opinion, they are all essential PM abilities.

7 Likes

I’ve spoken with several teams using wikis or some decision document repository and found some common themes with Google Drives filled with linked documents or collections of confluence pages to be a nightmare if you’re looking to pull on a decision thread. If you didn’t write those documents (and sometimes even if you did), prepare to see where the rabbit hole goes. Plus, they often lack a clear persistent connection to the list of information you outlined above and tend to become stale immediately after publishing.

I’m working on building a visual documentation & decision-making tool that connects the dots between product strategy & execution/experimentation (https://vistaly.com). We’re looking to provide a visual map for exploring product decisions and collaborating on new ones. Internally, we’ve been considering it as GitHub (version control) for Product.

Many people say “searching and finding the information” is essential (and they are correct). Still, I believe the more significant challenge is connecting the dots to all the other moving pieces without reading and internalizing the company’s intranet.

6 Likes

Medium to high fidelity prototypes with an accessible source of information containing all of your design criteria an excellent wiki page or document.

5 Likes

In project management its called a R.A.I.D. log and you document all of your risks, assumptions, issues and decisions in it.

We do this in confluence and link it to the high level Jira ticket.

4 Likes

For this, there is no set rule.

The PM must include information in the ticket description itself if the “specific product decision” will have a significant influence on a large number of users, deal with fundamental security, “may” be irreversible, or be in a key route of usage. Before assigning a task to an engineer, the PM or backlog manager would frequently request an approval cycle from the GPM.

In other instances, we can decide to exclude the justification entirely or only briefly mention it. We generate so much paperwork already that it would be impractical and not yield a significant return on investment for us to type out justification for every small move.

3 Likes

Very interesting question. Even if it is not fully documented or tracked, I think it is crucial to be able to show the logic behind how a feature was decided upon. However, it’s crucial to trace a decision’s roots back to the users, the evidence, and the objectives—even to the user interview that provided the initial inspiration.

2 Likes

Rationale or approach is pretty common. I think you’re doing the right things, just some imposter syndrome in your language.

We created Decision as an Issue type in Jira, with comments noting the rationale and who was consulted etc., then linked to the appropriate Epic / Stories.

1 Like

I don’t know if you use Jira, but linking a Confluence doc containing your product discovery and justification for that feature to the ticket might be helpful.