Thoughtworks Technology Podcast Caring about documentation in the LLM era (w/ Heidi Waterhouse)
16 snips
Jul 24, 2025 Heidi Waterhouse, a seasoned public speaker and documentarian, dives into the essential role of documentation in today’s AI-driven software landscape. She and host Lilly Ryan discuss how human insight is vital in capturing what AI often misses, especially in technical writing and prompt engineering. They also explore the importance of indexing for information accessibility and the balance between AI automation and accurate communication. Plus, hear about her upcoming book, Progressive Delivery, aimed at connecting software delivery with business value.
AI Snips
Chapters
Books
Transcript
Episode notes
Documentation Bridges Humans and Computers
- Documentation describes software to humans, just as code does to computers.
- Most people use documentation when frustrated because they can't get software to work.
Document for Human Understanding
- Only build documentation if you want others to understand or use your software.
- If the software is for yourself alone, documentation isn't necessary.
AI Works Best with Clear Documentation
- Well-structured APIs with explicit intentions suit AI-generated documentation well.
- AI struggles with ambiguous human contexts like dress codes or medical instructions.
