Project Structure, Naming, and Documentation

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 Searchcraft 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 Searchcraft 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 is 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 initially 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: donmackinnon.dev.

Resources Mentioned

• A Philosophy of Software Design by John Ousterhout
• John Ousterhout’s Maintainable.fm Interview (Episode 131)
• Searchcraft
• 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
• donmackinnon.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:

• Apple Podcasts
• Spotify

Or search "Maintainable" wherever you stream your podcasts.

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