Maintainable

• Lorna Mitchell: Writing Documentation Engineers Will Actually Read

  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 Websiterst2pdf ProjectSimon Willison’s Post on One-Person ProjectsHow to Take Smart NotesOpenAPI SpecificationVeil Prose LinterFollow Lorna:GitHubIndieWebThanks 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 PodcastsSpotifyOr search "Maintainable" wherever you stream your podcasts.Keep up to date with the Maintainable Podcast by joining the newsletter.

  --------  

  43:18
• Carola Lilienthal: Tackling Technical Debt with Patterns and Domain Knowledge

  Episode SummaryIn 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 TakeawaysModularity 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 MentionedCarola’s LinkedInWPS WebsiteCarola’s books:Sustainable Software ArchitectureDomain-Driven Transformation (English version coming soon)Modularity Maturity Index OverviewBooks Carola recommends:Reinventing Organizations by Frédéric LalouxTeam Topologies by Matthew Skelton and Manuel PaisBe 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 PodcastsSpotifyOr search "Maintainable" wherever you stream your podcasts.Keep up to date with the Maintainable Podcast by joining the newsletter.

  --------  

  43:00
• Joel Hawksley: The Hidden Costs of Frontend Complexity

  Topics DiscussedThe 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 PriorityThe 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 SystemPrimer fosters consistency but introduces the challenge of making changes across a vast, interconnected system.[00:12:54] The Cost of Frontend ComplexityJoel 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 AccessibilityJoel 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.ResourcesJoel Hawksley’s WebsitePrimer Design SystemAxe Accessibility ToolsGitHub’s ViewComponent FrameworkBook Recommendation:How Buildings Learn by Stewart BrandGuest's LinksJoel Hawksley on GitHubJoel Hawksley’s WebsiteThanks 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 PodcastsSpotifyOr search "Maintainable" wherever you stream your podcasts.Keep up to date with the Maintainable Podcast by joining the newsletter.

  --------  

  46:13
• Austin Story: Making Software Easier to Change, Remove, and Evolve

  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 TakeawaysSimplicity 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 MentionedYAGNI (You Aren’t Gonna Need It)GraphQL Federation OverviewDoximity Technology BlogThe Mom Test by Rob FitzpatrickAustin Story on LinkedInAustin Story's WebsiteStay ConnectedFollow Austin:LinkedInWebsiteThanks 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 PodcastsSpotifyOr search "Maintainable" wherever you stream your podcasts.Keep up to date with the Maintainable Podcast by joining the newsletter.

  --------  

  47:08
• Dan Moore: Building Developer-Friendly Authentication Solutions

  Topics CoveredCharacteristics of Maintainable SoftwareDan 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 SystemsDan 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 ChallengesAs 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 TeamsAdvice 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 RoleFrom 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 TakeawaysConsistency 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 MentionedFusionAuth BlogDan's Personal BlogCIAM Weekly NewsletterDan’s Book: Letters to a New DeveloperZen and the Art of Motorcycle MaintenanceThe Asimov story mentionedTry FusionAuthDownload FusionAuth: Get started with the self-hosted version today.Free Trial of FusionAuth: Experience the FusionAuth cloud for free!Connect with DanLinkedInBlueSkyThanks 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 PodcastsSpotifyOr search "Maintainable" wherever you stream your podcasts.Keep up to date with the Maintainable Podcast by joining the newsletter.

  --------  

  49:20

Mais podcasts de Tecnologia

Podcasts em tendência em Tecnologia

Sobre Maintainable