Writing the Shipwreck
summary
Walks into an actual documentation shipwreck with an obsolete Gitbook CLI deprecated toolchain, broken HTML, missing style and review processes, and no onboarding docs; chooses MKDocs + Material, wires CI/CD and ownership so every markdown file requires a tech‑writer review, uses AI to convert HTML to Markdown and to tighten prose, adds plugins like auto refs and macros to stop link rot, and reports that the new site and workflows actually work and scale.
AI-written summary · about
chapters (14)
- 0:00Introduction
- 0:43Documentation shipwreck
- 2:35Self-reflection
- 5:46Finding your crew
- 6:08Reconnaissance on docs
- 12:57Broken best practices
- 17:46Salvage the shipwreck
- 18:50Documentation structure
- 21:18Open-source tools
- 25:36Planning upgrades
- 27:21Incremental improvements
- 30:09Summary
- 31:18Timing considerations
- 33:27Q&A
related talks
38mWelcome to the World of Technical Writing: A Guide for Newcomers
20mJourney Of Devops Teams in a Corporate Environment
22mWrite Prose, Not just programs
39mSearch First-Writing for non-writers
41mLevel Up: Onboarding that enables writers to thrive
25mFor the Love of Go: How to Contribute Really
34mFrom Graffiti Writer to Technical Writer
49mLeaving a legacy: a guide to being kind to those who come after