Maintainable
Lorna Mitchell: Writing Documentation Engineers Will Actually Read
Jan 28, 2025
Lorna Mitchell, an open source advocate and technical writer, shares her expertise on creating documentation that engineers actually read. She discusses the vital role of documentation in software maintainability and the challenges of reviving old projects like RST2PDF. Lorna emphasizes API governance and introduces four levels of API readiness to enhance usability. Additionally, she shares practical tips for improving technical writing using tools and strategies that make complex information accessible and relatable for developers.
43:18
Episode guests
AI Summary
AI Chapters
Episode notes
Podcast summary created with Snipd AI
Quick takeaways
- Comprehensive documentation is essential for both new and returning users, serving as a foundation for the long-term sustainability of software.
- Effective API governance involves structured readiness levels, ensuring usability and consistency for enhanced developer experience with well-documented interfaces.
Deep dives
Characteristics of Well-Maintained Software
Well-maintained software is characterized by its accessibility and clarity, enabling new and returning users to engage with it easily. Key indicators include comprehensive documentation, which outlines the purpose, installation instructions, and user guidelines for various groups such as new users and contributors. This documentation serves not only to prepare the user for interaction but also to facilitate long-term sustainability of the software, reflecting its potential for a long lifespan. The presence of automated tests is another hallmark of healthy software, as it ensures ongoing functionality and aids in the ease of future modifications.
Remember Everything You Learn from Podcasts
Save insights instantly, chat with episodes, and build lasting knowledge - all powered by AI.
