The return of tech specs

When I was studying computer science as an undergraduate from 1996 to 2000, I took a course called Software Engineering that focused on the formal process of developing software. We learned to write a functional requirements document describing what the application should do, followed by a technical specification outlining how the software would achieve that. Only after completing both documents, often a semester-long effort with multiple review cycles, were we allowed to write any code. At the time, I didn’t realize it, but we were being taught the waterfall process.

In the early days of software engineering, the field looked to other industries for guidance on how to professionalize. The waterfall process came from manufacturing, where building physical products is expensive and hard to change once development begins. That approach made sense for software too, back when applications were shipped on physical disks. But as the internet grew and web applications became the norm, that rigid process started to fall apart.

My professional experience. In my early career, I still saw tech specs from time to time, but they gradually faded away. After the release of the Agile Manifesto, teams began looking for ways to speed up development. While the Manifesto doesn’t mention documentation at all, many took it as permission to skip it entirely. After all, most software engineers don’t get into the field because they’re excited about writing specs. The new norm became chatting with a product manager and then jumping straight into coding.

By the time I became tech lead on the Yahoo homepage rewrite in 2008, tech specs had mostly disappeared from the company. But with a project that large, involving over 20 engineers across four countries, I brought back a formal spec process for all new features. The team wasn’t thrilled. I heard all the usual complaints: it’s a waste of time, we need more time to code, this shows a lack of trust, I’m acting as a gatekeeper. Still, with support from my director, we stuck with it. And something interesting happened. The number of production issues dropped noticeably for features that followed the spec process compared to those that didn’t. Even better, years later, when a mostly new team was trying to understand the codebase, the old specs became valuable references for how things worked.

My ESLint experience. I relearned this lesson while maintaining ESLint. As more features were added over the years, it became harder to remember how everything worked, including the parts I built myself. Eventually, we introduced an RFC process that served the same purpose as a tech spec for new features. This gave the team and the community time to review large changes, identify issues, and explore solutions. The result was better features with fewer problems. And whenever we need to look back at a decision, the RFC is there to remind us not just of what was done but why.

AI and tech specs. All my experience with tech specs has convinced me they are an important part of software development. That’s why I’m excited to see AI-assisted programming moving in this direction. I’ve already shared my process of using AI to create a product requirements document (PRD) and a tech spec before asking Copilot to implement a major change. Since then, tools Windsurf’s planning mode, Cursor’s default planning, and Amazon’s new IDE Kiro have focused on creating implementation plans before coding.

I’m confident that going forward, software engineers will need to relearn how to create detailed tech specs for complex changes. It’s also likely that AI will help write and review these specs before implementing them. It’s time to embrace tech specs again because they can be a key to advancing your career.

Key Takeaways

• Traditional tech specs, once common in software development, faded with Agile but remain valuable for reducing errors and clarifying complex projects.
• Reintroducing formal documentation processes can improve team communication and long-term code maintainability, especially on large, distributed teams.
• AI tools are beginning to support the creation and review of tech specs, signaling a future where combining human insight with AI assistance will enhance software quality and career growth.

Understanding JavaScript Promises My e-book, Understanding JavaScript Promises, now includes information about Promise.withResolvers() and a whole new chapter on using and creating abortable functions. Buy the E-book

Stuff I've Enjoyed this Month

📝 npm 'is' package hijacked in expanding supply chain attack by Kirill Boychenko, Sarah Gooding
July saw a highly-orchestrated attack on the npm registry, effectively gaining access to and publishing compromised versions of several popular packages. This article outlines what happened, which packages were affected, and how social engineering is still one of the most dangerous forms of attack.

🎬 Cracks in AI productivity bull case by CNBC
Tech companies love to tout how AI is improving productivity, but there's some research that shows these productivity gains are concentrated among the least experienced engineers.

📝 It's time for modern CSS to kill the SPA by Jono Alderson
Single-page applications (SPAs) have been the state of the art for a long time now, but do they need to be? This post explores all of the modern CSS tricks that can make ordinary, multi-page applications look and feel like SPAs.

🎬 What's new in web UI by Una Kravets (Chrome for Developers)
Chrome continues to push more functionality directly into HTML and CSS, and this video gives an overview of what you can do today with very little JavaScript: custom dropdowns, carousels, and hovercards, oh my!

📝 Adding a permission system to Node.js by James Snell (NearForm)
Deno popularized the idea of permission systems in JavaScript runtimes. How practical would it be to add to Node.js? Longtime Node.js contributor James Snell explores the complexity of the problem and why a solution isn't straight forward.

🎬 Build epic startups: NotebookLM and Gemini 2.5 workflow by Blazing Zebra
This video is the best example I've seen of using AI to go from product concept to working prototype without writing a single line of code.

What I'm Working On

🏠 Real Estate: The midwest, where my properties are located, was hit by tornadoes and flooding. I was lucky that only one property sustained any damage. The basement flooded which then damaged the hot water heater and furnace. Both were repairable, thankfully. The sump pump in the basement just couldn't keep up with the speed with which the water was coming in. Follow my Instagram for real estate photos.

🎧 Podcast: I was on the JS-Craft podcast to talk about AI-assisted programming, JavaScript, and longevity in software engineering.

🍞 Bredbox: When Pocket shut down, I was really disappointed because I used it all the time. So, I decided I would make my own. Bredbox is my not-yet-released clone of Pocket that I'm hoping to make available soon. I have a lot of plans for this project and I'm pretty excited about it.

💻 ESLint:

• I spent a lot of time on a large internal refactor around lint violation reporting.
• I also spent time reviewing pull requests. We've had a lot of new contributors in the past couple of months and that has meant a lot of pull requests to review.
• I continued working on improved CSS parsing in our fork of CSSTree.

Coaching for Tech Leads and Staff+ Engineers

If you're a tech lead or staff+ engineer, chances are your manager has no experience in your role. While they may be well-intentioned, they may not know how to help you grow in such a challenging position.

That's where working with me can help. As a former tech lead and principal engineer at multiple companies, I learned firsthand the ins and outs of these roles. I work with my clients one-on-one to develop their leadership, communication, organization, and problem-solving skills to succeed in the upper ranks of the individual contributor track.

​