Skip to content(if available)orjump to list(if available)

Incrementally correct personal websites

Incrementally correct personal websites

March 22, 2020

I first heard of the phrase "incremental correctness" from Guillermo Rauch during our Design Details interview over 2 years ago.† Since then, the concept has been weaving its way through all parts of my life, inside and outside of design and technology. It's become a mantra of sorts at GitHub, thanks to the reliable repetition of the phrase in almost every conversation with Max Schoening.

Incremental correctness is the process of iterating towards something more truthful, accurate, usable, or interesting. The faster we can iterate, the faster we can discover good ideas. Things aren't perfect today, but tomorrow things can be slightly closer to perfect.

Incremental correctness changes everything about the way you work. It's anti-perfectionism. It's pro-generation. It's about discovery and proof, research and prototyping, and having a framework to reliably test your instincts. It discourages major redesigns, preferring isolated improvements to a small subset of nodes in any kind of working tree.

I've always struggled to have this mindset when working on my personal website. I get stuck in these loops where I redesign the thing once every few years, and am left so thoroughly exhausted and frustrated by the process that I don't want to touch the thing ever again. If you've ever dreaded the notion of having to redesign your portfolio, you probably know what I mean.

One of the reasons I get stuck in this trap is because our tools don't afford incrementally-correct processes.

Think about blogging for a second: the fact that a list of posts is ordered chronologically by publication date, by default, is a bug in our incrementally-correct worldview. Blogging tools don't create any incentive to go back and edit previous ideas or posts. Or, at the very least, the default ordering has a de facto side effect of fewer people being aware of revisions or reversals to previously-published ideas.

RSS feeds are organized linearly by publication date, putting pressure on writers make sure that each post is "final" – there's no going back to improve or clarify your thoughts for a feed reader where everything is static and cached for eternity. At the very least, any subsequent edits will only reach a fraction of the initial audience.

To combat this, I'm going to order the posts here by when they were last updated. But of course, this has flaws: not every update is an iteration on the underlying idea. Maybe I'm just fixing a typo, or swapping out a confusing word. The closest comparison I can think of is that blog post edits are treated like a semver minor version by default. I wish blogging tools could distinguish patches from minor versions, and interpret the impact of my change accordingly.

Regardless of this clear shortcoming, this ordering still feels incrementally more correct than ordering by publication date. Progress!

Let's talk about dependencies, everyone's favorite part of building websites.

If you've ever maintained a website for any length of time, you probably know just how frustrating it can be to let dependencies get out of date. Heaven forbid you return to a year-old project only to discover that half of your libraries are out of date, no longer supported, or require an entirely different set of local tooling to use. These are some of the reasons people hate building personal websites – there is too much effort spent on the meta-maintenance, and most people don't have the patience for it.

In this arena, tools have gotten better. A process I've found that has saved me hours of work and countless headaches is to set up an automatic dependency upgrade pipeline, backed by end-to-end tests, to ensure that my website won't break as underlying dependencies change. Using Dependabot, Cypress, and Vercel, my website is set up to automatically update dependencies, ensure that pages work correctly with the new code, and deploy directly to production with every merge. Think of this pipeline like a system for automating incremental correctness. Underlying bug fixes flow seamlessly into production without conscious effort. Magic.

And then there are deployments.

I used to dread making changes to my personal sites because I'd have to deploy them. Usually this meant running some kind of script locally, or to get old school, FTP-ing files to production and hoping I didn't break the whole thing. Deploying changes is another kind of meta-maintenance that most people hate.

Thankfully, the tools have gotten better. With Vercel, a production deploy is just a git push away – every single change to the master branch on my repo triggers a production deployment. It's a beautiful abstraction to eliminate the meta-maintenance of deploying code.

So here we are: I'm simultaneously frustrated by and invigorated by the tools available today to build websites. Some of them, like blogging platforms, place too much emphasis on creating static chunks of information. This discourages ongoing iteration, thus discouraging the pursuit of incremental correctness. Conversely, a lot of the meta-maintenance work of testing, deploying, and updating code has become infinitely easier.

If you've been struggling with the looming task of redesigning your personal website from scratch, or rebuilding your portfolio after years of neglect, maybe it's time to approach things from a different angle the next time around.

What if your website was a mini-product, just for you? How would you structure it differently? How would you think about process and accessibility? What systems would you set up to automate the boring parts and prevent regressions? What tools would you want to use that would afford a 5-minute daily check-in to make a small improvement to the content or design?

† The segment starts around minute 55, although I'd recommend the entire episode as Guillermo is incredibly thoughtful and forward thinking about many of these ideas.