When Agile Fails: Working on Large Documentation Projects
summary
A large SUSE docs suite of 30,000 lines of AsciiDoc spread across 10 books accumulates structural debt that Agile sprints won't fix; a proof‑of‑concept during Hack Week, reader interviews and a seven‑question survey surface navigation pain, then a plan using the JoAnn Hackos five‑phase model maps content into a new structure. Work is tracked via a Google Docs tracking spreadsheet while changes land in git — 60 pull requests and 170 commits — yielding improved search, consistent headings, and measurable progress across books.
AI-written summary · about
chapters (28)
- 0:00Intro
- 0:25We all age
- 1:13This talk is about
- 1:49The Documentation Suite
- 2:28The History
- 3:09Agile Development
- 4:07Docs as Code
- 5:05Technical Writers
- 6:23Buyin
- 7:01Proof of Concept
- 8:39Getting buyin
- 9:16Plan plan plan
- 10:36Set out
- 11:28Research
- 12:59What your readers want
- 13:31Stop moving things around
- 14:49User task analysis
- 17:58Track your work
- 18:43Real tracking
- 19:41Agile Ecosystem tracking
- 20:40Review
- 21:50Format
- 23:52Technical Debt in Documentation
- 25:06The Constant Hamster Wheel
- 25:45Do Your Research
- 27:03Outreach
- 28:14Conclusion
- 28:33QA
related talks
46mYour Personal Tech-Writing Agile Manifesto (or: Scrum is not a 4-character word)
39mThe Documentation Dream: One Team, No Silos, Shared Goal
43mFinding the line: Balancing business continuity and documentation debt
26mWe're Agile, We Don't Do Documentation
48mAgile from the Open Source Trenches
18mAgile leadership and technical mastery, a harmonious alliance
26mOrganizational Dysfunctions - Agile to the Rescue
49mAgile is a Dirty Word