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