Episode Highlights

[00:00:48] What Makes Software Maintainable
Don explains why unnecessary complexity is the biggest barrier to maintainability, drawing on themes from A Philosophy of Software Design.

[00:03:14] The Cost of Clever Abstractions
A real story from a Node.js API shows how an unused abstraction layer around MongoDB made everything harder without delivering value.

[00:04:00] Shaping Teams and Developer Tools
Don describes the structure of the Search Craft engineering team and how the product grew out of recurring pain points in client projects.

[00:06:36] Reducing Complexity Through SDK and Infra Design
Why Search Craft intentionally limits configuration to keep setup fast and predictable.

[00:08:33] Lessons From Consulting
Robby and Don compare consulting and product work, including how each environment shapes developers differently.

[00:15:34] Inherited Software and Abandoned Dependencies
Don shares the problems that crop up when community packages fall behind—especially in ecosystems like React Native.

[00:18:00] Evaluating Third-Party Libraries
Signals Don looks for before adopting a dependency: adoption, update cadence, issue activity, and whether the library is “done.”

[00:19:40] Designing Code That Remains Understandable
Why clear project structure and idiomatic naming matter more than cleverness.

[00:20:29] RFCs as a Cultural Anchor
How Don’s team uses RFCs to align on significant changes and avoid decision churn.

[00:23:00] Documentation That Adds Context
Documentation should explain why, not echo code. Don walks through how his team approaches this.

[00:24:11] Type Systems and Maintainability
How Don’s journey from PHP and JavaScript to TypeScript and Rust changed his approach to structure and communication.

[00:27:05] Testing With Types
Stable type contracts make tests cleaner and less ambiguous.

[00:27:45] Building Trust in AI Systems
Don discusses repeatability, hallucinations, and why tools like MCP matter for grounding LLM behavior.

[00:29:28] AI in Developer Tools
Search Craft’s MCP server lets developers talk to the platform conversationally instead of hunting through docs.

[00:33:21] Improving Legacy Systems Slowly
The Strangler pattern as a practical way to replace old systems one endpoint at a time.

[00:34:11] Deep Work and Reducing Reactive Noise
Don encourages developers to carve out time for uninterrupted thinking rather than bouncing between notifications.

[00:36:09] Measuring Progress
Build times, test speeds, and coverage provide signals teams can use to track actual improvement.

[00:38:24] Changing Opinions Over a Career
Why Don eventually embraced TypeScript after originally writing it off.

[00:39:15] Industry Trends and Repeating Cycles
SPAs, server rendering, and the familiar pendulum swing in web architecture.

[00:41:26] Experimentation and Team Autonomy
How POCs and side projects surface organically within Don’s team.

[00:44:42] Growing Skills Through Intentional Goals
Setting learning targets in 1:1s to support long-term developer growth.

[00:47:19] Where to Find Don
LinkedIn, Blue Sky, and his site: donmckinnon.dev.

Resources Mentioned

A Philosophy of Software Design by John Ousterhout
John Ousterhout’s Maintainable.fm Interview (Episode 131)
Search Craft
Elastic
Algolia
WordPress Plugin Directory
Request for Comments (RFC)
Strangler Fig Pattern
C2 Wiki
Model Context Protocol (MCP)
Glam AI
Aubrey/Maturin Series by Patrick O’Brian
Master and Commander
donmckinnon.dev

Thanks to Our Sponsor!

Turn hours of debugging into just minutes! AppSignal is a performance monitoring and error-tracking tool designed for Ruby, Elixir, Python, Node.js, Javascript, and other frameworks.

It offers six powerful features with one simple interface, providing developers with real-time insights into the performance and health of web applications.

Keep your coding cool and error-free, one line at a time!

Use the code maintainable to get a 10% discount for your first year. Check them out!

Subscribe to Maintainable on:

Or search "Maintainable" wherever you stream your podcasts.

Keep up to date with the Maintainable Podcast by joining the newsletter.

Don MacKinnon: Why Simplicity Beats Cleverness in Software Design

Maintainable