Most organizations publish a lot of information. Roadmaps, OKRs, diagrams. But when someone asks why a choice was made, the room goes quiet. People remember fragments of a meeting, a Slack thread, a comment in a pull request. The decision exists, but its reasoning is missing. That absence is expensive. It forces teams to re-litigate choices, rediscover context, and tiptoe around invisible constraints.
Decision transparency is the habit of making the why visible. It is not about more documentation. It is about a small amount of writing at the right moment, placed where people will actually find it.
What decision transparency means in practice
For me, a transparent decision has three qualities. It is findable in under a minute by someone who did not attend the meeting. It is short enough that a newcomer can read it without a tour guide. It carries the trade-offs, not just the outcome.
The simplest tool for this is an Architecture Decision Record. Michael Nygard popularized ADRs as short, durable notes that capture a problem, the alternatives considered, the decision taken, and the consequences that follow. They do not try to be perfect. They try to be useful and searchable over time. A second tool is the request for comments. An RFC gives people a chance to react before a decision hardens, which is often where the best feedback emerges. Together, ADRs and RFCs turn private context into shared memory https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://github.com/joelparkerhenderson/architecture_decision_record https://innersourcecommons.org/.
Why this changes team behavior
When the reasoning is visible, people stop debating ghosts. They argue with facts. They can see which constraints mattered and which ones were incidental. Onboarding gets faster because the story of the system is not trapped in private chat logs. Teams learn together, not just work in parallel. Public organizations like GOV.UK have codified this mindset for years with a simple rule of thumb: make things open, it makes things better https://www.gov.uk/service-manual/service-standard/make-things-open-it-makes-things-better. GitLab’s handbook takes a similar stance and shows how decision logs scale when they are the default, not the exception https://about.gitlab.com/handbook/.
Where decision transparency breaks
It fails when the artifacts are written for compliance instead of understanding. You see this in ADRs that read like press releases, or RFCs that are published after the work is mostly done. It also fails when decisions are scattered. A note in a wiki, another in a private doc, a third in a ticket that will be archived in six months. People stop trusting the record because the record cannot be found.
The other failure mode is performative speed. A decision is announced as final, and the document appears after the fact to justify it. That kills feedback and pushes dissent into private channels.
How to keep it lightweight and real
Keep the bar low and the placement obvious. One directory in the repo. One template everyone can fill in under ten minutes. A link from the pull request that implements the change. Short is a feature. If a decision needs ongoing history, add a follow-up ADR or a small changelog section rather than turning one note into a novel.
When a decision genuinely lives outside code, put it where the team lives. For many teams that is the handbook. For others it is an engineering decision log that links back to issues and PRs. The important part is a single place people learn to search first. GOV.UK’s principle survives because it is both a value and a habit. Make things open, then make them easy to find.
The leader’s part in this
Leaders can lower the temperature by writing the first ADR themselves and by accepting edits to their own reasoning. They can also insist on the boring parts that keep the system healthy. A decision that is not discoverable is not transparent. A decision that cannot be challenged during an RFC is not a decision, it is a decree. Model the behavior you want to see. Write briefly. Explain trade-offs. Change your mind in public when the facts change.
Try this
For the next two weeks, write ADRs for only two kinds of decisions: anything that changes a public interface and anything that locks the team into a vendor or framework for more than six months. Use a three minute template with four headings: context, options considered, decision, consequences. Link each ADR from the relevant pull request and from a single index file at the root of the repo. At the end of two weeks, ask two engineers who were not involved to find the why behind a recent change. If they can do it in under a minute, you are on the right track.
Next
4/6: Work Transparency - Showing Progress Without Micromanagement
Sources
Michael Nygard, “Documenting Architecture Decisions” (ADR pattern)
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
https://github.com/joelparkerhenderson/architecture_decision_recordInnerSource Commons, RFC and cross-team collaboration patterns
https://innersourcecommons.org/GOV.UK Service Manual, “Make things open: it makes things better”
https://www.gov.uk/service-manual/service-standard/make-things-open-it-makes-things-betterGitLab public handbook, transparency and decision logs
https://about.gitlab.com/handbook/