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:

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.

Lorna Mitchell: Writing Documentation Engineers Will Actually Read

Maintainable