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
forum Ask episode
web_stories AI Snips
view_agenda Chapters
menu_book Books
auto_awesome Transcript
info_circle Episode notes
volunteer_activism ADVICE
Characteristics of Well-Maintained Software
Prioritize documentation, automated tests, and easy onboarding for maintainable software.
Ensure the software is accessible and easy to understand, both for new and returning users.
volunteer_activism ADVICE
Documentation Expectations
Clearly state the project's purpose and target audience in the documentation.
Include instructions for different user groups (new users, contributors, maintainers).
question_answer ANECDOTE
Maintaining RST2PDF
Lorna maintains RST2PDF, a Python library, despite not being a Python developer.
She and her co-maintainer adopted the abandoned project and modernized it.
Get the Snipd Podcast app to discover more snips from this episode
One Simple Technique to Boost Writing, Learning and Thinking – for Students, Academics and Nonfiction Book Writers
Sönke Ahrens
This book introduces the Zettelkasten method, a note-taking system developed by Niklas Luhmann. It emphasizes the importance of creating a reliable and simple external structure to compensate for the limitations of our brains. Ahrens explains how to organize notes in a way that fosters deep thinking, learning, and writing. The method involves taking atomic notes, linking ideas, and using a slip-box to store and connect these notes. This approach helps in developing a lifelong pool of rich and interconnected ideas, enhancing productivity, and improving critical thinking and writing skills[2][3][5].
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.
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!
Maintainable 