Caring about documentation in the LLM era (w/ Heidi Waterhouse)
Thoughtworks Technology Podcast
Thoughtworks
4.7 • 53 Ratings
🗓️ 24 July 2025
⏱️ 39 minutes
🧾️ Download transcript
Summary
In an age of vibe coding and LLMs, do we really need to care about documentation? Do we need to spend time and energy producing it — time when we could just be shipping code? Of course we do; particularly if we want to communicate and share software with other humans.
To discuss documentation in 2025, Technology Podcast host Lilly Ryan is joined by Heidi Waterhouse, a very special guest with an esteemed and varied career in technical communcation.
In this episode, Lilly and Heidi tackle the challenges of documentation in a world increasingly infused with AI-generated code and text, explore whether prompt engineering is really just technical writing in disguise and examine the difficulties of writing for highly specific audiences.
They also cover Heidi's Progressive Delivery, an upcoming book about bridging the gap between software delivery and business value. It's due to be released in the latter part of 2025 and written alongside James Governor, Kim Harrison and Adam Zimman.
Find out more about Heidi Waterhouse by visiting her website: https://heidiwaterhouse.com/
Learn more about Progressive Delivery: https://itrevolution.com/product/progressive-delivery/
Transcript
Click on a timestamp to play from that location
| 0:00.0 | Hello and welcome to the ThoughtWorks Technology Podcast. |
| 0:11.0 | I'm one of your regular hosts, Lily Ryan. |
| 0:13.6 | Joining me today, we have Heidi Waterhouse. |
| 0:15.9 | Heidi is a public speaker, a documentarian, writer, collaborator, progressive delivery thinker, and many other kinds of things. |
| 0:24.9 | She's working in marketing advisory, and her second book, Progressive Delivery, is coming out in November 2025. |
| 0:31.1 | She joins us today to talk about AI and documentation, a topic that I think many of us are thinking about quite a lot at the moment. |
| 0:40.1 | And if we're not, we should be. Heidi, welcome to the show. |
| 0:43.6 | It's good to be here. |
| 0:44.6 | Your second book, as I said, is coming out in November. |
| 0:47.7 | Your first book, though, was in 2021, which was Docs for Developers. |
| 0:51.3 | And you've been a technical writer for, I think, most of your career, if I'm not wrong. |
| 0:55.3 | So what is documentation to you? Documentation is the way we describe software to humans, just like |
| 1:04.6 | code is the way we describe software to computers. And software is something that sits in the |
| 1:10.5 | middle of our work processes and our humanity and our computers. And software is something that sits in the middle of our work processes and our |
| 1:13.4 | humanity and our computers. So when I'm talking to people about documentation, I really want to |
| 1:21.1 | figure out why they're using it. And the primary reason that almost everyone uses documentation is because they're angry. |
| 1:29.4 | By the time you're reading documentation, you're usually pissed off because you haven't been able |
| 1:33.9 | to do a thing with software. Knowing that makes me understand that what people are trying to do |
| 1:40.1 | with both software and documentation is get their work done and not use a computer. |
| 1:46.6 | There are actually very few people in the world who wake up in the morning and think, |
| 1:51.1 | I would like to use a computer. |
| 1:53.9 | That's fair and reasonable. |
... |
Please login to see the full transcript.
Disclaimer: The podcast and artwork embedded on this page are from Thoughtworks, and are the property of its owner and not affiliated with or endorsed by Tapesearch.
Generated transcripts are the property of Thoughtworks and are distributed freely under the Fair Use doctrine. Transcripts generated by Tapesearch are not guaranteed to be accurate.
Copyright © Tapesearch 2025.