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

EP-109 | November 1, 2021 | 46:31




Discover why documentation is more than just a necessity—it's a key part of maintainable software. Heidi Waterhouse delves into the hidden challenges and rewards of keeping your documentation in check.





## Show Notes

In this episode of Maintainable, Robby Russell chats with Heidi Waterhouse, Transformation Advocate at [LaunchDarkly](https://launchdarkly.com/) and contributor to "[Docs for Developers](https://link.springer.com/book/10.1007/978-1-4842-7217-6)." 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](https://heidiwaterhouse.com/)
- [Heidi's Twitter](https://twitter.com/wiredferret)
- [Heidi's LinkedIn](https://www.linkedin.com/in/heidiwaterhouse/)
- Order the new book, [Docs for Developers](https://link.springer.com/book/10.1007/978-1-4842-7217-6), that Heidi is a co-author of
- Blog post: [When you stare into the blank page, it stares back at you](https://heidiwaterhouse.com/2021/10/04/when-you-stare-into-the-blank-page-it-stares-back-at-you/)
- Video: [Lillian Gilbreth: First Lady of Engineering](https://www.youtube.com/watch?v=_9RlfBdLvE8)

 








## Transcript