Heidi Waterhouse: Documentation: The Best Diff is a Red Diff

In this episode of Maintainable, Robby Russell chats with Heidi Waterhouse, Transformation Advocate at LaunchDarkly and contributor to "Docs for Developers." Heidi shares her insights on the crucial role documentation plays in software maintenance, how to manage documentation debt, and why "the best diff is a red diff."

Episode Highlights

• [00:00:53] Heidi's Take on Maintainable Software: Discussing the characteristics of well-maintained software, with a focus on modularity and context-aware decisions.
• [00:02:16] Documenting Context in Code: The importance of leaving behind the rationale for past decisions to help future developers understand trade-offs.
• [00:04:09] Stress vs. Creativity: The mental firewall between stress-driven fixes and creative problem-solving and how it affects documentation.
• [00:05:53] Making Documentation a Habit: Techniques for leaving helpful notes in code and why documenting as you go is crucial.
• [00:07:12] Documentation Debt: Exploring the concept of documentation technical debt and how it parallels code technical debt.
• [00:09:49] Pruning Documentation: Strategies for regularly reviewing and archiving outdated documentation to keep the signal strong.
• [00:12:02] Templating Documentation: How to start documenting without the fear of a blank page using templates and examples.
• [00:14:01] Where to Document: Tips on deciding the best place to store documentation and ensuring it is easily accessible.
• [00:18:47] The Pitfalls of Video Tutorials: Why video tutorials can be a time bomb and the importance of searchable, updateable documentation.
• [00:21:12] Starting with Public Speaking: Heidi's journey into public speaking, starting with anger-driven topics and evolving to educational resources.
• [00:26:26] Dealing with Rejection in Public Speaking: The reality of talk proposal rejections and why it's not a reflection of your value as a speaker.
• [00:30:14] Code Ergonomics: How the physical layout of code and workspace can affect developer productivity and reduce context switching.
• [00:36:39] Improving Documentation Culture: Advice for new team members on finding allies and starting small to improve documentation practices.
• [00:40:15] Integrating Documentation with Code: Making documentation part of the code review process and defining it as part of the "done" criteria.

Key Takeaways

• Documentation is a crucial part of maintaining software, and its importance should not be underestimated.
• Regularly pruning and archiving outdated documentation helps keep the information relevant and useful.
• The best way to combat documentation debt is by making documentation an integral part of the development process.
• Public speaking can start small and doesn’t require expertise—passion and personal experiences are powerful drivers.

Helpful Links

• Heidi's Website
• Heidi's Twitter
• Heidi's LinkedIn
• Order the new book, Docs for Developers, that Heidi is a co-author of
• Blog post: When you stare into the blank page, it stares back at you
• Video: Lillian Gilbreth: First Lady of Engineering

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.