Stop diagramming, start designing
How to increase DX in your team - a conversation with KellyAnn Fitzpatrick on the MonkCast
👋 Hi, this is Thomas, with a new issue of “Beyond Code: System Design and More”, where I geek out on all things system design, software architecture, distributed systems and… well, more.
QUOTE OF THE WEEK:
“Developers often use diagrams to tackle a fundamental communication challenge: conveying the complexities of a distributed software system — including its components, dependencies, and APIs — clearly and effectively to a distributed team.” - me, Thomas Johnson 🙂
I was recently interviewed for a three-part series on MonkCast, RedMonk’s podcast, where I discussed the shift from diagramming to system design with KellyAnn Fitzpatrick.
Here’s my summary — and a bit more — of that conversation.
The Changing Landscape of Software Development
Building software today is not the same as it was even just a few years ago. Very few people are designing and building complex distributed systems solo. It’s a team sport (more on that in my next issue).
These are main differences I see:
Systems are more complex with thousands of components, dependencies, and APIs. The rise of distributed architectures, cloud-native applications, SaaS, APIs,, composable platforms, ageing of software and the proliferation of legacy systems has added layers of complexity.
Systems are more dynamic: Modern software systems are ever evolving. This is both a function of the adoption of agile, modern design practices (e.g. Evolutionary Architecture) and the pace of technological advancement.
Changing engineering team dynamics: Roles are more specialized and teams are more distributed. Coordinating across different cross-functional teams, offices, and time zones, introduces numerous communication challenges.
In short, the experience of building software is drastically different today.
The Impact of Documentation and Technical Debt
Good documentation and manageable technical debt are two key factors in creating a positive Developer Experience (DX).
When a developer joins a team, one of the first questions they ask is, "What is your software?" and that’s a tough question to answer.
Poor, incomplete, or inaccurate documentation is a common grievance in the tech community, where developers lament the hours spent on manually writing documentation, searching scattered sources for information, or enduring unnecessary meetings to piece together the full picture.
Good technical documentation is crucial and saves considerable time: lack of visibility and understanding of your software can create bottlenecks, slows development, and results in fragile, inflexible systems.
In short, it compounds on the technical debt, impacting negatively the developer experience: when you can’t make informed, contextual decisions, you also can’t foresee and prevent all the (negative) consequences your changes will have on the rest of the system.
Why Traditional Diagrams Aren’t Enough
The typical response to gaining visibility into a system is to create diagrams. While “visualizations” are good (a picture is worth a thousand words, after all), traditional diagramming tools were not built to represent modern distributed system, and have several limitations.
Static by Nature: Traditional diagrams are static, while modern systems evolve continuously. The pace of change makes it hard to keep diagrams up-to-date without excessive manual work (almost everyone has the experience of creating a diagram and seeing it become out-of-date the next day).
Limited Collaboration: With complex systems, engineers need to be able to easily communicate changes to their team, and for their team to be able to easily see the diffs and changes and offer feedback.
Lack of Context: Diagrams often lack insight into the reasoning behind architectural choices, trade-offs, and requirements.
Insufficient for Debugging: A static high-level overview doesn’t offer the detailed insight necessary to troubleshoot issues, as many problems require different levels of abstraction
A Call for System Design Tools
To bridge these gaps, developers need design tools that do more than visualize—they should provide:
A comprehensive and current view of the system architecture, and of the system behavior so that the team can make informed decisions and catch breaking changes before they occur.
A single source of truth that reflects the full history and context of the system.
Automation of documentation reducing manual work and freeing up developer time.
Sometimes switching tools can be a struggle. My advice is not to look at it in terms of switching tools, but in terms of making your team more productive, reducing manual work, and saving them time.
Get the developers their hours back, get the happiness up, and embrace the future of auto-updating system design tools.
This is the full conversation with KellyAnn Fitzpatrick:
📚 Interesting Articles & Resources
“Don’t fix it just because it’s technical debt” - Dan Slimmon
The short article discusses the common misconception that all technical debt must be addressed immediately. It argues that not all technical debt is inherently problematic and that prioritizing technical debt fixes should be strategic. In short: only address technical debt when it genuinely impedes progress, productivity, or scalability.
“Not Just Scale” - Marc Brooker
AWS engineer Marc Brooker examines the challenges and strategies of scaling distributed systems efficiently, focusing on insights from high-scale tech companies. While he acknowledges the impressive capabilities of modern hardware, he lists many reasons for embracing distributed architectures.
“Discovering WebSockets with some Coding“ - Vivek Bansal
The article explores WebSockets, a protocol enabling two-way, persistent communication between client and server. Understanding WebSocket fundamentals can help developers optimize systems that rely on fast, bidirectional data flow.