Why > What: Documenting Decision Making

In the process of making software, systems, or digital products, it’s important to document the technical decisions made along the way. Oftentimes this manifests as a product spec, technical spec, or system architecture diagram. As a project grows, ADRs, RFCs, or *IPs (improvement proposals)¹ might be used to garner consensus and document decisions. In other instances, the backstory might be buried in PRs/commit messages, meeting minutes, or nowhere at all (implicit, or tribal knowledge).

This type of information is critical for keeping current and future stakeholders informed. And it can also lend credibility when someone encounters an unexpected design decision.

A few weeks ago, many were outraged over an API design choice in Vercel’s Workflow DevKit. They chose to use directives — similar to 'use strict' — which many deemed non-portable outside of the Vercel ecosystem. When they shared their reasoning—the alternatives explored, the trade-offs considered—the conversation shifted. People understood, even if they still disagreed.

As this demonstrates, the decision itself is less interesting than how it was arrived at. Interesting is maybe not the best word - what I mean is: conclusions are often meaningless without context. What are the goals and constraints? What assumptions were made? What alternatives were considered? What are the trade-offs?

My favorite way for documenting these types of decisions is a flavor² of IBIS, or Issue-based Information System. While IBIS is typically graphical, teammates at Agoric used a textual notation to facilitate dialogue mapping. It’s quick to write, concise to read, and effective for eliciting feedback.

Anatomy

There are three core elements to IBIS notation:

• Issues: questions or problems that need to be addressed
• Positions: possible answers or solutions to the issues
• Arguments: pros and cons for each position

The syntax is quite simple: top-level Issue sections start with a question mark (?). Positions are denoted with an indented colon (:). And beneath each Position are Pros and Cons denoted with plus (+) and minus (–) symbols. Below is a toy example:

? How should the app authenticate users?
  : Use OAuth (Google/Apple)
    + Users trust these providers
    + Supports MFA (YubiKey, 2FA)
    - Not everyone has those accounts
  : Email + password
    + Works for all users
    - Security burden on us

The syntax can also capture decisions — Positions can be denoted as accepted, rejected, or tentative-accepted. Issues can be completed, obsolete, or open. Below in our updated toy example, :+ indicates an accepted position, :~ indicates tentatively accepted, and ?! denotes the issue as completed (resolved):

?! How should the app authenticate users?
  :+ Use OAuth (Google/Apple)
    + Users trust these providers
    + Supports MFA (YubiKey, 2FA)
    - Not everyone has those accounts
  :- Email + password
    + Works for all users
    - Security burden on us
  :~ Magic link
    . Note: Revisit Magic link after OAuth MVP
    + Smooth UX
    - Email deliverability risks

It also scales nicely: you can use it for planning large-scale projects or for micro-decisions of much less consequence. It takes pressure off any one “decision maker” and puts the weight on a clear, shared process. The structure makes it easy for others to spot gaps, propose alternatives, or challenge assumptions without wading through a long narrative. Conversations shift from defending decisions to improving them.

Tooling

While tooling is quite limited at the moment, my colleague Turadg made a web app where you can write your own IBISs. It supports the syntax in a WYSIWYG editor and renders the output in a format with stronger visual hierarchy (outlines, colors). My favorite feature is Ctrl+Space input suggestions — it’s great for limiting the cognitive load on newer users and increasing adoption.

Conclusion

The main takeaway here is not that you need to adopt IBIS syntax. Although if you wanted to, that’d be pretty cool — I think we could all use more concision in our lives.

Rather, understand that the why is more important than the what. Share your assumptions, share your line of reasoning, and guide others towards the conclusions you’ve made.

When you seek feedback from others, it becomes easier for them to see where you’re coming from. More importantly, it highlights where you might have your blinders on — positions you haven’t considered or mistakes in your assumptions or understanding.

Footnotes

1. Ethereum Improvement Proposals, Python Enhacement Proposals, ECMAScript Proposals, etc. ↩

2. I say “flavor” of IBIS since it’s typically represented graphically without an official text syntax. Future iterations, like gIBIS and Compendium, are also graphical representations. GPT‑5.1 Thinking claims Argdown is maybe the closest text-first relative. ↩