Writing, Alignment and Design Work

I’m very deliberate about recording what I’ve done, and why. I write a lot - first so I can recall things later, and second to add context for someone else coming back to work I’ve done via Git, Jira, or documentation. I have a lot of personal docs, and where it’s appropriate I share it and circulate what I’ve learned. I have read, and shared, the HashiCorp “Writing Practices and Culture” blog post many times in different roles.

Incidents are where this matters under pressure. A clear write-up, a timeline, who did what, what worked and what didn’t—is how understanding gets out of the incident channel and spreads across the team. Without that, you don’t just suffer an outage—you leave the lesson concentrated in one or two people’s heads.

When it was just Armon and me, we wrote everything down because it helped us clarify what we were doing, and kept us from falling down rabbit holes of solving problems that didn’t exist. Mitchell Hashimoto, Co-Founder and CTO

I’m very aware that most of what we write goes unread.

But I still take enormous pleasure in writing git commits that explain why I built something, or the problems I had along the way that meant I discarded solution A, B and C.

I enjoy writing Architectural Decision Records, Requests for Comment, and quick exploration write-ups on whatever just surfaced on Hacker News. I’ll tell you what I was thinking, where I got stuck, and how I got to the answer.

Writing is how we communicate and get aligned with others, and alignment is what proves we share the same goals.

Design work is often seen as a solitary and boring activity. I’ve only realised as I’ve become more senior that it’s not. Design work ensures alignment, and allows us to validate what we’ve built against our plans and intentions.

Maggie Appleton at GitHub has written about the importance of alignment, and collaboration in design work on Ace, a GitHub Next prototype for shared, multiplayer coding-agent sessions.

She says the usual touch points for alignment—Slack conversations, Zoom discussions, comments on issues and PRs—have gone away because the building phase has been compressed. The time and cost of implementation have shrunk considerably.

By the time the code was reviewed and merged, the whole team had seen the work happening and was roughly on the same page.

In what I’m seeing day to day, AI-assisted or generated pull requests often feel bigger and slower to review. Context switching seems heavier now that AI is in the loop. Finding alignment at review time is too late—implementation might be cheap now, but we’ve got to ensure we build the right things.

… that creates more touch points for alignment, they’re on the wrong side of the implementation.

Instead of jumping right into prompting and waiting for the golden goose—AI output—we should spend more time planning, designing and writing. LLMs are good at interpreting this input, and humans can make use of it too.

Our agentic tools should help us do higher quality work, get aligned faster, and build a few exceptional things, rather than a thousand crappy ones.

Here’s to the writers.