A Pretty Good Idea
Engineer: "Oooh, that's a pretty good idea, gotta build it!"
Blank IDE: "Do you know exactly what it is?"
Engineer: "Umm...I have a pretty good idea..."Barring Samuel Taylor Coleridge levels of inspiration†, it’s rare to envision a project from scratch with enough clarity and detail to make a polished product. Even working with AI, this is an issue. You can tell the AI to “make it polished” but if you aren’t really sure what “it” is, your description will be vague. The AI will produce something. That something will be the AI’s idea of highly polished, but likely well off-target. Not only will the inference used in the polishing be wasted, the result will be so dialed in with detail that it will be harder to evaluate the core shape than if it were rougher.
Make it work at all. See the shape of it. Then start honing (and honing)‡.
Embrace the Ugly (at First)
During that first pass you need to be comfortable with the ugly. Don’t get sidetracked trying to fix that thing you just can’t stand before you know what it is you’ve got. You may end up axing that entire chunk two hours from now. This is especially true when you’re incorporating tools or libraries you’re not super familiar with. You can’t pick the best place to pitch your tent until you’ve seen the terrain. When it’s in “working at all” shape you can look at it from altitude and see the patterns. You’ll see where you were repeating things that could be unified. You’ll find the places you expected something to be harder than it was and over-engineered. And you’ll find the messes where you underestimated the complexity and had to hack a path through the mistake to close the loop.
Fold It. Spindle It. Even Mutilate It. But Don’t Chuck It.
There’s an old coder adage: “Throw the first one away”. While that’s not categorically false, it’s also not the first choice to reach for. Unless your exploratory version was in a language you can’t deliver in, there’s a lot of value in transforming what you have instead of starting over. “Throw the first one away” was coined in the days before modern, fast, version control. Code is more safely malleable than it has ever been. Aside from saving your product manager from a heart attack, the biggest advantage of morphing in place over discarding and rewriting is having a working version§ the entire time. This means you can continuously compare your new behaviors against the previous ones and verify that only the desired changes occurred. If you’re part of a team, it also means others can work in tandem with your changes instead of being blocked until you catch your rewrite up to the prototype.
A Brief Example
This is the last time I’m going to mention this site as an example of an engineering principle. It’ll be the third time‖, and that’s all anyone gets. The first pass at getting this site stood up was definitely ugly - the .md -> .html “workflow” was asking Claude to do it. Then I switched to a pandoc-based system with Makefiles for dependency tracking, but it had specific rules for each source/target pair and a pretty brittle design in general.
After getting that working, I extracted the structure into a separate repo and made it generic so I could share it with other people. There is nothing like knowing other people are going to see your code to make the deficiencies jump out at you. It’s like inviting people to come over tomorrow, then looking around your living room and realizing just how much cleaning there is to do.
The latest (probably not last) iteration made it not only usable, but livable¶. It’s easy to add stuff, change stuff, remove stuff. A single make target keeps everything up to date including table of contents, RSS feed, and icons. It’s now doing the job it was made for: letting me focus on writing instead of wrangling. This will do nicely until I need something it doesn’t handle (yet).
TL;DR
Highly transferable wisdom boils down to a simple sequence, so here it is: Ugly it. Eyeball it. Transmogrify it. Ship it.
Footnotes
† ↩︎ And self-medication
‡ ↩︎ and hon…you get the idea.
§ ↩︎ Important caveat: working does not mean backward compatible. When you’re making something new, chaining yourself to backward compatibility with a prototype is a path to madness. Save the backward compatibility for when it’s worth money, not just a bit of convenience.
‖ ↩︎ The other two strikes: Deshittification, Automation vs. AI
¶ ↩︎ You can check it out here: markdown-web-1.0-workflow