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.