Join Robby as he chats with Lorna Mitchell, open source advocate and technical writer, about the art of creating documentation that doesn’t gather dust. Lorna shares her experiences as a maintainer of the open source project RST2PDF, the value of API governance, and how documentation bridges gaps in developer experience.

Highlights:

• What Makes Software Maintainable: Characteristics like great documentation, automated tests, and onboarding ease.
• Documentation's Role in Long-Lived Software: Why it’s crucial for internal tools and open source projects alike.
• Open Source in Practice: Lorna’s journey with RST2PDF and adopting a tech stack she wasn’t initially fluent in.
• API Governance Simplified: Lorna explains the four levels of API readiness and how teams can work toward more usable APIs.
• Writing Documentation for Engineers: How style guides can empower contributors without overwhelming them.
• Using Tools to Improve Documentation: From linters to prose-checking tools like Veil, Lorna discusses practical tips.

Key Takeaways:

• [00:01:00] What makes software well-maintained: documentation, accessibility, and automated tests.
• [00:03:10] Why documentation isn’t just for new users—Lorna’s experience with revisiting her own open source projects.
• [00:06:30] Diving into rst2pdf: Challenges in maintaining an abandoned project.
• [00:13:45] Balancing ownership and transitioning open source projects to new maintainers.
• [00:15:30] What is OpenAPI, and how does API governance impact usability?
• [00:26:10] The art of concise yet helpful documentation for different audiences.
• [00:33:00] Using examples in APIs to enhance clarity and reduce confusion.
• [00:40:00] Tools for improving writing, from prose linters to markdown syntax checkers.

Resources Mentioned:

• Lorna Mitchell’s Website
• rst2pdf Project
• Simon Willison’s Post on One-Person Projects
• How to Take Smart Notes
• OpenAPI Specification
• Veil Prose Linter

Follow Lorna:

• GitHub
• IndieWeb

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.

Episode Summary

In this episode of Maintainable, Robby sits down with Carola Lilienthal, Software Architect and Managing Director at WPS. Together, they explore the intersection of cognitive science and software architecture, strategies for tackling technical debt, and why simplicity, modularity, and domain knowledge are crucial for maintainability.

Carola shares her approach to improving legacy systems, fostering domain-driven development, and introducing sustainable patterns into software design. She also discusses the Modularity Maturity Index (MMI), a tool her team has used to assess and improve over 300 systems.

Topics Covered

• [00:00:43] What makes software maintainable?
• [00:01:24] The importance of clear structure, modularity, and simplicity in software.
• [00:02:38] How patterns help reduce complexity and onboard developers faster.
• [00:04:42] Addressing the challenges of systems with mixed architectural patterns.
• [00:06:20] Strategies for fostering creativity while maintaining simplicity.
• [00:07:05] How to guide teams to balance technical experimentation and maintainability.
• [00:14:03] Practical techniques for documenting architecture and decisions.
• [00:16:17] What is the Modularity Maturity Index (MMI), and how does it measure system health?
• [00:18:02] Common mistakes in managing technical debt and how to avoid them.
• [00:21:20] Why domain knowledge is essential for innovation and problem-solving.
• [00:33:03] Evolving legacy systems with domain-driven design and transformation.

Key Takeaways

• Modularity matters: Simplified, modular systems with high cohesion and loose coupling reduce cognitive load and technical debt.
• Patterns as a shared language: Establishing a pattern language within your team creates consistency and eases onboarding.
• Cognitive science in software: Architecture aligned with how our brains process complexity results in more maintainable systems.
• Domain knowledge drives innovation: Teams should focus their creativity on solving domain-specific problems, not over-complicating the architecture.
• The value of architecture documentation: Keeping clear decision records helps teams navigate legacy code and onboard new developers.

Resources Mentioned

• Carola’s LinkedIn
• WPS Website

Carola’s books:

• Sustainable Software Architecture
• Domain-Driven Transformation (English version coming soon)
• Modularity Maturity Index Overview

Books Carola recommends:

• Reinventing Organizations by Frédéric Laloux
• Team Topologies by Matthew Skelton and Manuel Pais

Be sure to follow Carola on LinkedIn and X.

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.

Topics Discussed

• The importance of changeability as a core characteristic of well-maintained software.
• How GitHub has approached accessibility as a business and legal imperative.
• The evolution of GitHub’s frontend system, spanning over 2,000 pages, and the concept of "frontend vintages."
• Primer: GitHub’s design system and the paradox of its success—consistency vs. changeability.
• The disproportionate maintenance costs of frontend systems compared to backend systems.
• Using tools like Axe and keyboard-only tests to identify and resolve accessibility issues.
• The philosophical balance between creativity and usability in software design.
• Practical advice for teams starting their accessibility journey with limited resources.
• How frontend complexity affects scalability, especially in app-like experiences.
• Joel’s advocacy for adopting off-the-shelf components to reduce complexity for smaller teams.

Key Takeaways

[00:01:12] What Defines Well-Maintained Software?

Joel explains how changeability—the confidence to make and deploy changes—provides the foundation for high-quality software.

[00:03:05] Accessibility as a Priority

The Microsoft acquisition drove GitHub’s investment in accessibility, introducing SLAs, automated tools, and manual processes to track progress.

[00:08:49] Primer: GitHub’s Design System

Primer fosters consistency but introduces the challenge of making changes across a vast, interconnected system.

[00:12:54] The Cost of Frontend Complexity

Joel shares how browser quirks, device diversity, and other variables make frontend maintenance far more expensive than backend systems.

[00:28:05] Where to Start with Accessibility

Joel recommends focusing on key user workflows like signing up, making payments, and completing core tasks. He emphasizes the importance of tools like Axe and keyboard-driven tests.

Notable Time-Stamps

• [00:01:12] What Makes Software Well-Maintained? Joel shares how changeability drives quality.
• [00:03:05] GitHub’s Accessibility Journey: The role of SLAs, audits, and automation.
• [00:08:49] Primer and Design Systems: Balancing consistency with innovation.
• [00:12:54] The Hidden Costs of Frontend Complexity: Lessons learned at GitHub.
• [00:20:33] Balancing Creativity with Usability: Joel reflects on the intersection of design and functionality.
• [00:28:05] Accessibility Best Practices: Where teams should focus their initial efforts.

Resources

• Joel Hawksley’s Website
• Primer Design System
• Axe Accessibility Tools
• GitHub’s ViewComponent Framework

Book Recommendation:

• How Buildings Learn by Stewart Brand

Guest's Links

• Joel Hawksley on GitHub
• Joel Hawksley’s Website

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.

Austin Story, Senior Engineering Director at Doximity, joins Robby to explore the intricacies of building maintainable systems, fostering team accountability, and enabling faster iteration without sacrificing quality. Austin shares how his team approached migrating from a monolithic GraphQL architecture to a federated model, why simplicity matters for long-term success, and how guiding principles like YAGNI influence his decision-making.

Doximity is a leading digital platform for medical professionals, and their technology blog offers deep dives into the systems and tools that power their innovative solutions.

Key Topics Discussed

• [00:00:41] What is maintainable software? Austin highlights key traits, including testability, simplicity, and ease of removal.
• [00:02:09] Designing for removability: Why it's important and how it enables iterative progress.
• [00:03:05] YAGNI (You Aren’t Gonna Need It): How this principle shapes Austin's approach to feature development.
• [00:04:13] Migrating to GraphQL Federation: Benefits of breaking up a monolithic GraphQL server and the challenges faced during the transition.
• [00:05:56] GraphQL vs. REST: How GraphQL aids developer productivity while maintaining backward compatibility.
• [00:10:53] Collaboration between data and application teams: Using tools like Kafka to bridge gaps and improve workflow.
• [00:17:00] Upgrading Ruby on Rails applications: Balancing autonomy with central guidance for seamless updates.
• [00:27:55] Fostering ownership on teams: The cultural practices that empower engineers to take initiative and drive results.
• [00:34:29] Prioritizing work effectively: How Austin's team uses quarterly planning and measurable "goalposts" to align efforts with impact.
• [00:40:00] Avoiding bike-shedding: Keeping meetings and reviews focused on meaningful progress.

Key Takeaways

• Simplicity Wins: Maintainable software is easier to adapt, remove, and iterate on when it's kept simple.
• Iterate and Refine: Use principles like YAGNI to avoid over-engineering and ensure systems are built to evolve.
• Collaboration Drives Success: Bridging communication between specialized teams can unlock untapped potential.
• Focus on Outcomes: Define clear goals and track measurable results to ensure projects align with business needs.

Resources Mentioned

• YAGNI (You Aren’t Gonna Need It)
• GraphQL Federation Overview
• Doximity Technology Blog
• The Mom Test by Rob Fitzpatrick
• Austin Story on LinkedIn
• Austin Story's Website

Stay Connected

Follow Austin:

• LinkedIn
• Website

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.

Topics Covered

Characteristics of Maintainable Software
Dan emphasizes the importance of internal consistency in codebases, automated tests, and proper documentation to preserve decision-making context.

• [00:05:32] Internal consistency: Why it matters.
• [00:08:09] Lessons from maintaining legacy codebases.

Working with Legacy Systems
Dan shares stories of upgrading ORM frameworks, introducing caching systems, and transitioning to bug tracking tools.

• [00:09:52] Replacing custom ORM systems with Hibernate and Ehcache.
• [00:13:10] Tackling high-risk components with automated testing.

Modern Authentication Challenges
As part of FusionAuth, Dan discusses building developer-friendly tools that balance local flexibility with SaaS convenience.

• [00:21:05] FusionAuth’s role in secure authentication.
• [00:28:13] Testing authentication flows locally and in CI pipelines.

Navigating Constraints in Teams
Advice for managing technical debt, advocating for team priorities, and communicating with stakeholders during lean times.

• [00:16:39] Communicating the impact of resource constraints.
• [00:19:27] Tracing single requests to understand complex systems.

Industry Trends and AI's Role
From managed services to the impact of AI on coding languages, Dan reflects on how the industry continues to evolve.

• [00:35:05] Managed services as accelerators for maintainability.
• [00:41:25] The potential and limits of AI in software development.

Key Takeaways

• Consistency and documentation in codebases reduce cognitive overhead for developers.
• Understand how your software fits into the business to prioritize effectively.
• AI might reshape the industry, but it won’t replace the need for thoughtful problem-solving.
• Opinionated frameworks like Ruby on Rails continue to offer exceptional developer ergonomics.

Resources Mentioned

• FusionAuth Blog
• Dan's Personal Blog
• CIAM Weekly Newsletter
• Dan’s Book: Letters to a New Developer
• Zen and the Art of Motorcycle Maintenance
• The Asimov story mentioned

Try FusionAuth

• Download FusionAuth: Get started with the self-hosted version today.
• Free Trial of FusionAuth: Experience the FusionAuth cloud for free!

Connect with Dan

• LinkedIn
• BlueSky

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.

In this episode of Maintainable, Robby speaks with Tom Johnson, Co-Founder and CEO of Multiplayer. Tom shares his perspectives on the evolving landscape of distributed systems, the challenges of maintaining legacy software, and how innovative tools are transforming the way teams collaborate.

Topics Discussed

• Characteristics of well-maintained software, from system-level documentation to effective workflows.
• The importance of debugging tools tailored for distributed systems.
• Anecdotes about managing technical debt, including cutting off a CEO’s database access.
• How auto-documentation and design branches in Multiplayer streamline team collaboration.
• Practical strategies for tackling technical debt and fostering developer morale.

Key Takeaways

• [00:01:16] Defining Well-Maintained Software: Tom explains why documentation, tests, and collaborative workflows are essential.
• [00:06:14] The Case for Locking Down Production: Lessons learned from a humorous but cautionary tale.
• [00:18:11] Debugging Distributed Systems: How Multiplayer’s tools simplify the debugging process.
• [00:25:00] Design Branches and Team Collaboration: Enhancing communication through shared documentation.
• [00:31:39] Prioritizing Technical Debt: Identifying customer and developer pain points.

Resources Mentioned

• Multiplayer
• Tom Johnson on LinkedIn
• Tom Johnson on Twitter
• Book Recommendation: Making Comics by Scott McCloud

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.

In this episode of Maintainable, Robby speaks with Gulcin Yildirim Jelinek, a Staff Database Engineer at Xata. Joining from Prague, Czech Republic, Gulcin discusses her experiences working with legacy databases, the evolution of Postgres, and her passion for building accessible tech communities.

Gulcin shares practical insights into modern database management, including the rise of automation tools like YAML and Pgroll, as well as how extensions like pgvector are unlocking new possibilities for Postgres users. Her work with the Prague PostgreSQL Meetup and Diva Conference highlights her dedication to fostering inclusive and welcoming tech communities.

Episode Highlights

• [00:05:32] What Makes Databases Maintainable? Gulcin reflects on documentation, onboarding, and usability.
• [00:15:10] From Legacy to Modern: Challenges with legacy systems in hospitals and banks and the transition to Postgres.
• [00:22:18] Pgvector and Vector Search: Introducing Postgres extensions to enable vector-based queries.
• [00:28:12] Scaling Automation with YAML: How YAML transformed database management and DevOps workflows.
• [00:33:00] Fostering Community and Accessibility: Gulcin’s work with Postgres Europe and Diva Conference.
• [00:36:15] Mythology with a Twist: Book recommendations featuring Circe and Elektra.

Key Takeaways

• Documentation Matters: A well-documented system ensures effective onboarding for both developers and end-users.
• Automation is Key: Tools like YAML and Pgroll streamline database operations, minimizing downtime and manual intervention.
• Inclusivity in Tech: Conferences and communities should prioritize accessibility, from catering to translation services.
• Vector Databases in Postgres: Pgvector is making Postgres a viable option for AI-driven workloads, eliminating the need for separate systems.

Resources Mentioned

• Xata Blog
• Pgroll
• Prague PostgreSQL Meetup
• Diva: Dive into AI Conference
• Kadin Yazilimci (Women Developers of Turkey)
• Circe by Madeline Miller
• Elektra by Jennifer Saint

Connect with Gulcin

• LinkedIn
• Prague PostgreSQL Meetup
• Diva Conference

Book Recommendations:

• Circe
• Elektra

Links:

• Kadin Yazilimci (Women Developers of Turkey)
• Diva: Dive into AI Conference
• Prague PostgreSQL Meetup
• On X
• Xata Blog
• Pgroll

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.

Robby sits down with Justine Gehring, an AI Research Engineer at Moderne, to explore how AI tools are transforming code maintenance and scalability. They dive into the unique ways AI can support refactoring for massive and legacy codebases, from retrieval-augmented generation (RAG) to lossless semantic trees, and discuss how developers can benefit from AI-assisted planning and refactoring.

Justine shares her background transitioning from academia to industry and reflects on the essential role of reproducibility in AI, why maintainable code is often overlooked in research, and the challenges of balancing innovation with real-world reliability in software projects.

Topics Discussed

• What Makes Software Maintainable: Justine’s take on good documentation, reusable code, and ensuring new team members can quickly navigate a codebase. [00:00:42]
• Academia vs. Industry in Code Maintainability: Why reproducibility and code maintenance often diverge in research settings, and how industry standards address this gap. [00:01:14]
• From Academia to AI Engineering: Justine shares her journey and how her background in machine learning led to a career in AI-focused software maintenance. [00:04:48]
• Scaling Refactoring with OpenRewrite: An introduction to OpenRewrite, the open-source tool that facilitates large-scale code transformations, developed by Moderne. [00:12:15]
• Lossless Semantic Trees: The benefits of LSTs for detailed code analysis, retaining essential syntax and type information critical for reliable AI refactoring. [00:20:24]
• Retrieval-Augmented Generation (RAG): Justine explains RAG’s significance in allowing AI models to provide context-specific responses without heavy re-training. [00:26:00]
• Trust and Validation in AI-Generated Code: The importance of robust test cases and human oversight when leveraging AI-generated code to avoid cascading errors. [00:31:36]
• AI as a Planning Tool for Refactoring Projects: Justine’s insights on using AI as a collaborative coding assistant, offering developers suggestions for planning refactoring and maintenance tasks. [00:35:24]
• Real-World Example of Scaling Refactoring: Justine recounts a case study where Moderne used OpenRewrite to facilitate large-scale code migration involving multiple frameworks. [00:42:00]
• Advocating for AI Tools in Code Maintenance: Tips for developers interested in introducing AI tools and approaches within their teams or organizations. [00:42:31]

Key Takeaways

• AI Supports Reproducibility and Reliability: Ensuring reproducibility in AI-driven tools can enhance both credibility and usability for complex codebases.
• Prioritize Planning Before Refactoring: Understanding code dependencies and structure is key to successful refactoring; AI tools like OpenRewrite can automate targeted changes.
• Human Expertise Remains Essential: AI can be an effective coding assistant, but human oversight is necessary to ensure accuracy and quality.
• Experiment and Scale: Start with small, impactful AI-assisted refactoring recipes and scale up once the process is reliable, saving significant development hours over time.

Resources

• Moderne
• Justine Gehring’s LinkedIn
• OpenRewrite Documentation
• Getting to Yes by Roger Fisher and William Ury

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.

As a product advocate at Nx, Katerina Skroumpelou combines her engineering skills with a knack for connecting with clients. In this episode, she shares how clear documentation, scalable architectures, and a collaborative culture can transform software development for the better.

Key Takeaways

[00:01:25] Katerina’s Background: Robby and Katerina discuss her career journey, starting in engineering and recently moving into product advocacy.
[00:02:29] Characteristics of Well-Maintained Software: Katerina highlights key aspects of maintainable software—readability, scalability, and reliability.
[00:04:39] Product Advocacy at Nx: Katerina describes her unique role, bridging technical support and customer outreach to ensure clients make the most of Nx tools.
[00:07:01] White Glove Approach: The “white glove” service approach allows Katerina to dive deep into clients' codebases, offering a hands-on approach to using Nx effectively.
[00:09:52] Scalable Documentation Practices: Balancing clarity and detail, Katerina provides tips on structuring code comments and READMEs to be concise yet thorough.
[00:12:09] Managing Technical Debt: Robby and Katerina discuss the importance of keeping code up-to-date and scalable, especially in large systems with high demands.
[00:16:00] The Importance of Collaboration: Moving from solo work to team-based code reviews taught Katerina the value of a collaborative approach to maintainable code.
[00:19:15] Nx’s Monorepo Solution: How Nx provides cache and build tools to optimize mono-repo performance, boosting both speed and organization within projects.
[00:22:12] Nx Cloud and CI: Katerina discusses Nx Cloud’s role in enhancing CI workflows by allowing parallel tasks and cache sharing across teams.
[00:24:07] When to Consider Monorepos: Katerina explains the benefits of monorepos for organizing codebases and improving scalability.
[00:26:37] AI Tools in Development: Katerina shares her enthusiasm for new AI tools like StackBlitz’s Bolt and their potential to streamline app development.
[00:29:00] Finding Motivation at Work: Advice for developers who feel stuck or unmotivated in their current roles and ways to reconnect with the work they enjoy.

Resources Mentioned

• Nx Dev
• StackBlitz Bolt.new

Books:

• The Three-Body Problem by Cixin Liu
• Cryptonomicon by Neal Stephenson
• Slaughterhouse-Five by Kurt Vonnegut

Katerina's social profiles:

LinkedIn
Twitter
Bluesky

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.

Welcome to another engaging episode of the Maintainable Software Podcast! In this episode, Robby sits down with Moriel Schottlender, Principal Software Engineer at the Wikimedia Foundation, to explore the complex journey of modernizing MediaWiki, the software behind Wikipedia. Moriel shares her insights on what it takes to keep an enormous monolithic codebase maintainable while supporting an ever-growing and diverse set of global users. She highlights the importance of modularization, ownership, and the delicate balance between flexibility and stability in open-source software.

Key Takeaways

[00:00:51] Characteristics of Well-Maintained Software: Moriel discusses the three crucial characteristics of well-maintained software: ownership, modularization, and documentation.

[00:01:09] Ownership and Rules for Contribution: Ownership goes beyond just fixing bugs—it involves understanding the architectural purpose and maintaining consistency even as teams change.

[00:03:35] Product Vision's Role in Maintainability: Why a clear product vision is essential for maintaining software, even in the face of organic growth.

[00:07:14] Balancing Experimentation and Long-Term Planning: Moriel shares insights into how Wikimedia balances rapid experimentation with careful, long-term architectural planning.

[00:07:32] The Evolution of MediaWiki: MediaWiki's growth from a small project to the backbone of Wikipedia, now supporting over 900 wikis, and the challenges that come with scaling.

[00:14:18] Modernizing a 23-Year-Old Monolith: Robby and Moriel dive into the challenges of modernizing MediaWiki’s architecture, including the difficulties of updating a monolithic structure.

[00:17:15]Wikitext vs. Markdown: Moriel explains why MediaWiki uses its own Wikitext language instead of Markdown and the unique challenges it presents.

[00:22:25] Architectural Flexibility for the Future: The importance of having a flexible architecture that can adapt to the evolving needs of users and technologies.

[00:26:04] Technical Debt and Modularization: How Wikimedia approaches technical debt in MediaWiki and prioritizes architectural interventions to improve modularity and maintainability.

[00:39:00] Community Contributions to MediaWiki: Strategies for increasing developer contributions and how Wikimedia empowers volunteers while maintaining software quality.

[00:41:59] Advice for Aspiring Open Source Contributors: Moriel shares encouraging words for anyone looking to contribute to open-source projects, emphasizing that everyone can make a meaningful impact.

[00:35:44] The Role of Documentation: Moriel discusses Wikimedia's efforts to improve documentation and ensure it's useful for both developers and end-users, leveraging the strengths of wiki-based contributions.

[00:30:29] Celebrating Small Wins: Moriel talks about how Wikimedia celebrates small victories to keep team morale high in the face of big challenges.

Resources Mentioned

• Moriel's Website
• Moriel on Mastodon
• MediaWiki Documentation

Book Recommendation:

• Year Zero by Rob Reid

Connect with Moriel

• Moriel on LinkedIn
• Instagram
• Twitter
• GitHub
• Mastodon

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.

Welcome to another engaging episode of Maintainable! Robby sits down with Kate Holterhoff, Ph.D., a Senior Analyst at RedMonk and former front-end engineer, to explore the intricate world of software maintenance, documentation, and the future of developer roles. Kate brings her unique perspective from her time as a practitioner at a digital marketing agency, her academic background, and her current role in developer advocacy.

Topics Explored

[00:00:00] Introduction to Kate's Background: Robby and Kate discuss her journey from academia to front-end engineering and now to being a Senior Analyst at RedMonk. Kate shares how her experiences have shaped her perspective on software maintenance.

[00:04:00] Well-Maintained Software: Kate dives into her definition of well-maintained software, emphasizing modularity, semantic readability, and the importance of considering future developers who will interact with the code.

[00:11:30] The Challenges of Agency Work: Kate reflects on her time at a digital marketing agency, where she often worked on projects that had passed through many hands. She discusses the importance of balancing quick deliverables with maintainability.

[00:20:45] The Role of Documentation: Kate shares insights on the value of documentation for distributed teams, highlighting her experience organizing documentation sessions ("documentation paloozas") to capture team knowledge and ensure maintainability.

[00:30:00] RedMonk and Developer Advocacy: Kate explains her role at RedMonk and how the firm differs from traditional analyst firms like Gartner. She discusses RedMonk's focus on developers as key decision-makers in the tech landscape.

[00:39:15] Front-End Developers as Kingmakers: Robby and Kate explore how front-end engineers are increasingly influencing the adoption of tools and technologies within organizations. Kate describes this trend as front-end developers becoming "kingmakers" in the industry.

[00:49:50] AI and Developer Tools: Kate discusses the integration of AI into developer tools, the potential benefits, and challenges for junior developers. She emphasizes the importance of understanding how to read code in an AI-assisted world.

Key Takeaways:

• Emphasize modularity and semantic readability to ensure code can be easily maintained by future developers.
• Documentation is crucial for maintainability, especially in distributed and contractor-heavy teams.
• Front-end developers are becoming key decision-makers, influencing tool and technology adoption.
• AI is increasingly integrated into developer workflows, making it essential for developers to focus on reading and understanding code.
• The definition of a 'developer' is evolving, with more abstracted tools and AI playing a larger role in development processes.

Resources Mentioned:

• RedMonk
• Kate Holterhoff on LinkedIn
• Kate Holterhoff on Twitter
• Darwin's The Origin of Species

Episode Highlights:

[00:00:00] Introduction to Kate's Background

[00:04:00] Characteristics of Well-Maintained Software

[00:20:45] The Importance of Documentation

[00:30:00] What Does a Senior Analyst at RedMonk Do?

[00:39:15] Front-End Developers as Kingmakers

[00:49:50] The Role of AI in Developer Tools

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.