"How To Write Tech Documentation That Will Save Your Career"
summary
A clear claim: terrible internal docs can wipe production and cost jobs; a narrated incident at Big Tech Co (Ruby on Rails) shows a new hire running create database then seed with real credentials and obliterating production. Concrete fixes: searchable precise titles, clickable TOCs, code formatting and dummy credentials, store secrets in OnePassword, PR templates with checklists, short commit messages, explicit tickets about feature flags and data migrations; several live examples and a reusable PR template that actually worked at Valiant Finance.
AI-written summary · about
chapters (10)
- 0:00Intro
- 6:05Pick your title carefully.
- 7:16Provide clear structure.
- 8:50How To Run Database Migrations
- 12:05Tip #3: Update regularly.
- 16:17Tip #4: Make the most of code examples.
- 23:11Refine commit messages and PRs.
- 27:39Comment code where necessary.
- 32:16Write comprehensive specs.
- 37:47Cover the 4 Ws + How.
related talks
18mTechnical Documentation - How Can I Write Them Better and Why Should I Care?
13mTechnical documentation – how can I write them better and why should I care?
01h 24mWriting Documentation - Practices and Theory
38mThe Stuff You Don't Want to Write... Documentation
44mCreating a Culture of Documentation
47mThe Things You Don't Want to Write - Documentation
27mWrite Docs Devs Love: Ten Tips To Level Up Your Tech Writing
29mMove Fast and Document Things: Writing internal docs at fast-moving organizations