Simon Willison’s Weblog

Preferring throwaway code over design docs (via) Doug Turnbull advocates for a software development process far more realistic than attempting to create a design document up front and then implement accordingly.

As Doug observes, "No plan survives contact with the enemy". His process is to build a prototype in a draft pull request on GitHub, making detailed notes along the way and with the full intention of discarding it before building the final feature.

Important in this methodology is a great deal of maturity. Can you throw away your idea you’ve coded or will you be invested in your first solution? A major signal for seniority is whether you feel comfortable coding something 2-3 different ways. That your value delivery isn’t about lines of code shipped to prod, but organizational knowledge gained.

I've been running a similar process for several years using issues rather than PRs. I wrote about that in How I build a feature back in 2022.

The thing I love about issue comments (or PR comments) for recording ongoing design decisions is that because they incorporate a timestamp there's no implicit expectation to keep them up to date as the software changes. Doug sees the same benefit:

Another important point is on using PRs for documentation. They are one of the best forms of documentation for devs. They’re discoverable - one of the first places you look when trying to understand why code is implemented a certain way. PRs don’t profess to reflect the current state of the world, but a state at a point in time.