Publish the Decision, Not Just the Screenshot

The easiest part of building in public is showing that something happened. A new page is live. A component has been redesigned. The lighthouse score moved upwards. These updates can create momentum, but they rarely explain what the project is becoming or why one path was chosen over another.

A screenshot records an outcome. A decision record reveals direction.

Consider a publishing site that begins with a plan for a richly animated home page. The early prototype feels distinctive on a fast laptop. On an older phone, the movement stutters, the page takes longer to become useful and the visual hierarchy becomes harder to follow. The interesting update is not a before-and-after image. It is the decision: decoration will never delay access to the writing. That principle can guide image loading, typography, transitions and every later feature.

Publishing the decision helps the audience understand the work as a connected set of choices rather than a procession of artefacts. It also creates gentle accountability. Once a project states that reader attention matters more than ornamental motion, a future design can be evaluated against that claim. The principle may still change, but changing it now requires a reason.

This form of openness needs boundaries. Building in public does not mean live-streaming every uncertain thought, exposing private information or turning collaborators into characters in a personal narrative. A useful public record can be selective. It should describe the context, the options that were genuinely available, the tradeoff and what will be observed next. Confidential details can remain confidential. Half-formed opinions about other people can remain unwritten.

The timing matters too. A decision shared only after success can become a tidy origin story. The false starts disappear, and the chosen path begins to look inevitable. Sharing while there is still uncertainty preserves the most transferable part of the work: how a choice is made without knowing whether it will succeed.

One practical format is a short decision note. Start with the constraint. Perhaps a theme must remain maintainable by one person, or an experiment must run within a modest hosting budget. Then name the choice in plain language. Explain the strongest alternative, because a decision without an alternative is usually just a preference. Finally, state what evidence would prompt reconsideration.

For example: “I will use the platform’s native membership system rather than add a separate identity service. This limits custom workflows, but it reduces the amount of sensitive infrastructure I must operate. I will revisit the choice if members repeatedly need capabilities the native system cannot support.” That paragraph teaches more than a week of progress percentages.

Decision notes also improve the work privately. Writing forces vague instincts into sentences. “This feels too complex” may turn out to mean that the feature creates three new maintenance paths. “Users prefer it” may rest on two conversations and deserve a small experiment rather than a permanent rule. Public explanation exposes weak reasoning before code makes it expensive.

There is a risk that an audience can make a project timid. If every choice becomes a referendum, the builder may optimise for immediate approval and lose the coherence of the original idea. Building in public should invite evidence, not transfer ownership of every decision. Readers can reveal needs and consequences; they do not need to become an unpaid steering committee.

The record becomes especially valuable over time. A collection of decisions shows how the project’s direction developed. New contributors can see why an apparently odd constraint exists. Readers can distinguish an intentional limitation from an unfinished feature. The builder can identify recurring principles and contradictions.

There is no need for every note to become an essay. A useful decision record can fit on a card: date, context, choice, alternative, consequence and review trigger. Consistency matters more than ceremony. When the reasoning is brief enough to maintain, building in public becomes part of making the work rather than an additional publishing project competing with it.

Polished results still have a place. People enjoy seeing an idea acquire form, and visible progress can sustain the person doing the work. But the deeper contribution is a trail of reasoning others can inspect. Show the page, certainly. Then share the moment when the page taught you what the project should protect.