You Have the Empathy of a Goat: Documenting for the User
summary
Argues that useful documentation is specific: watching a salesperson reveal a CSV upload pain caused by an unsorted pulldown led to fixes that take under an hour; recommends commit messages with a first line under 50 characters, a blank line then a what-and-why body; endorses inline comments to explain why odd code exists; cites contributing docs via DocsDoctor.org that produce Rails PRs, even spawning the StrongLikeBull gem and career wins; explain the why.
AI-written summary · about
chapters (28)
- 0:00Intro
- 1:45Cows
- 3:12Ox
- 4:16Tara
- 5:48Documentation
- 6:24The User
- 7:04The Documentation
- 7:38Meetings are the Enemy
- 9:48The Curse of Knowledge
- 12:08Watch an end user
- 15:07Comment in code
- 17:13Commit Messages
- 19:00Form
- 19:58GitHub
- 20:43Documentation is automatic
- 21:45Write great commit messages
- 22:00Bird by Bird
- 22:44The Unsung Hero
- 23:16Practical Writing Tips
- 25:30The Secret to Writing
- 25:53Miscellaneous
- 26:05Getting Good at Writing
- 29:31Conversational Documentation
- 30:35Release Notes
- 30:58Commitments
- 32:35Recap
- 33:26Why all the goats
- 36:47How to encourage other people in the humanities
