Written in the margins
The negotiation in the margins is the documentation
·
5
min read
The documentation was never the problem. The problem was that half of it lived in people's heads.
Every component had a name. Most had a rough description. What they didn't have was the reasoning — why this pattern and not that one, where the edge cases lived, what a behavior meant when two components looked nearly identical. That knowledge existed. It just hadn't been asked for yet.
The process was simple by design. A draft per component, written as a starting point — something concrete enough to react to. The team worked through it asynchronously, leaving comments where something was unclear, contested, or missing.
Those comments are where the real work happened.
Dashboard header component doc with engineer comments, Google Docs
The draft set the terms. The comments negotiated them.
Size naming table with engineer's comment
Naming decisions that seemed settled in Figma turned out to be open questions the moment someone had to write them down.
Datepicker interaction with comments
Behavior that lived in institutional memory surfaced because the draft made it visible enough to dispute.
Tooltip anatomy with comments
Where guidance lives is a structural decision. The margins are where it got made.
Content guidelines with date formatting comment
Some standards didn't exist until someone asked the question. The writing process created them.
Slack thread, pagination scope
Some decisions outgrew the doc entirely. The question of whether pagination was its own pattern began in a comment thread and reshaped the system's information architecture.
Close to fifty components documented and published to a single Zeroheight reference site. One point of entry for design and engineering, in place of the fragmented references both had been navigating separately.
But the more durable outcome was structural. Documentation written through negotiation carries more than guidance — it carries the decisions behind the guidance. That's what makes it retrievable, by humans and by AI. Not the volume. The specificity.