Welcome back, Technical Documentation

I’ve been doing more heads-down software development in the past year than perhaps ever before. Working (mostly) alone on a codebase has been an incredibly freeing experience, filled with exhilarating highs, humbling moments, and constant learning opportunities. And yes, a bit of toil too. 😅

In this golden age of AI, I’ve come to a realization: we may have reached peak value for product and technical documentation.

In the early days of waterfall development, we would meticulously create detailed specifications, iterate on the product multiple times, and all teams would base their deliverables on those specs. It truly paid off to invest significant time in documentation; you could fend off your marketing team’s left wing suggestion with a confident “sorry, it’s not in the PRD!”.

Then came the era of agile and lean methodologies. The focus shifted to building, validating, and maybe but likely not, writing something up later. While backend systems still required some level of design artifacts depending on team size and organization, having bits and pieces of docs describing what a system should be or is was often not useful and, in the worst cases, a misleading waste of time. We evolved to rely on a set of docs to help folks get started, and after that, the mantra became “just look at the code.”

But today, things are different. We have someone (or rather, something) that actually reads the docs. And not just reads, but can build a product based on those docs. AI can enable us to turn our dreams into reality, but it first needs to know what those dreams are. The key lies in getting your dreams marked down for a document reader more diligent than any intern ever was. And our AI companions are barely opinionated! No more justifying your heretic choice of DynamoDB in endless meetings, hooray!

Feeding Cursor your instructions, crafting prompts that describe your vision, and specifying the components you want (often based on a pre-chat where you make those decisions) is the new way of bringing software vision to life. And this time, you reap instant rewards from the time you invest in those designs and thinking through your users’ or systems’ problems. You get working code and a functional product, almost instantly.

Just a few weeks ago, you could blame the AI for generating something silly. Now, we know that we can only blame ourselves for not thinking things through, and designing and documenting it well enough.

At least that’s how I feel on this current day. Tomorrow, who knows! Things are changing faster than ever before. Is this going to be a lasting situation, or will it be different next week? I’d love to hear your thoughts!