Maintainable - Lorna Mitchell: Writing Documentation Engineers Will Actually Read

Lorna Mitchell: Writing Documentation Engineers Will Actually Read

01/28/25 • 43 min

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:

Follow Lorna:

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.

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:

Follow Lorna:

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.

Previous Episode

Carola Lilienthal: Tackling Technical Debt with Patterns and Domain Knowledge

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 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:

Or search "Maintainable" wherever you stream your podcasts.

Keep up to date with the Maintainable Podcast by j...

Next Episode

Mike Bowers - From ISAM to JSON—Navigating 40+ Years of Database Evolution

Mike Bowers, Chief Architect at FairCom, has spent decades navigating the evolution of database technology. In this conversation, he and Robby explore the challenges of maintaining a 40+ year-old codebase, balancing legacy constraints with forward-thinking design, and the realities of technical debt.

Mike shares how FairCom transitioned from ISAM-based databases to modern JSON-driven APIs, the trade-offs between strict schemas and flexible document stores, and how software architecture plays a critical role in long-term maintainability. He also explains why human-readable JSON simplifies debugging, how documentation-driven development improves API usability, and why many software teams struggle with refactoring at the right time.

Topics covered

[00:05:32] The role of software architecture in long-term maintainability
[00:10:45] Why FairCom's legacy ISAM technology still matters today
[00:14:20] Transitioning to a JSON-based API for modern developers
[00:19:40] The challenges of maintaining 40+ years of C code
[00:24:10] Technical debt: What it really means and how to manage it
[00:28:50] The trade-offs between strict schemas and flexible NoSQL approaches
[00:34:00] When to refactor vs. when to start over from scratch
[00:38:15] The influence of product management thinking on software architecture
[00:42:30] Advice for engineers considering a shift into architecture roles

Resources Mentioned

Book Recommendation:

The Influential Product Manager by MSc Bucero

Thanks to Our Sponsor!

Need a smoother way to share your team's inbox? Jelly’s got you covered! 🍇✨

Jelly is perfect for small teams — because it was built by a small team. If you struggle with keeping your team’s knowledge organized and accessible, check out Jelly, a lightweight knowledge management tool designed to make finding answers easy—without all the clutter of traditional wikis. No more sticky situations or knowledge gaps—Jelly keeps everything smooth, and shareable.

Bonus for Maintainable listeners Get 20% off your first year at letsjelly.com/maintainable,

Subscribe to Maintainable on:

Or search "Maintainable" wherever you stream your podcasts.

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