Documentation Communities: Sound Strategy or Documentarian's Gambit?
summary
Migration moves docs out of one closed repo into each project repo so docs branch with code, add a public feedback button that files issues to ciladoc issues, and introduce a rewards program called the cila mvd program; toolchain uses sphinx theme plus doxygen and swagger for APIs, a veil linter, poetry for packaging, GitHub Pages hosting and ZenHub for boards; outcome is per-version docs, faster turnaround, 12 repos live so far, and a 60:1 developer to writer ratio.
AI-written summary · about
chapters (34)
- 0:00Introduction
- 1:24Companies with Open Source Docs
- 4:15What we had when I first joined
- 4:52We were lucky
- 5:25We wanted more
- 6:00We were missing
- 7:54Redesign
- 8:24No real complaints
- 8:38Back to the drawing board
- 9:10Looking at what we wanted
- 10:08Create a useful predictable structure
- 11:40Easy to contribute
- 12:02Get contributors involved
- 13:12Reviews
- 14:09Getting people on board
- 16:59reward
- 17:49MVD program
- 18:32Our solution
- 20:03Tool chain
- 20:59Sphinx
- 21:50Version Selector
- 22:33Feedback Loop
- 24:20What do we still need
- 25:08Component CMS
- 26:09Conclusion
- 26:54Thank you
- 27:07For listening
- 28:43How do you make docs part of the definition of done
- 30:27Would you still have considered opening up the docs
- 31:48Licensing and contributor agreements
- 32:49Lauras concerns
- 34:08Why create a separate repo
- 35:56What happens after the migration
- 38:13Contacting Laura
related talks
44mPushing documentation (so it doesn't hurt anymore)
47mEngineering Documentation
35mBuilding Docs like Code: Continuous Integration for Documentation
42mEngineering Documentation
45mDocs as Code Fix a poor documentation culture in your organization
24mEscaping the Curse of Outdated Docs
45mUseful and Beautiful Developer Docs and How to Create Them
40mDocs Tools for OSS Maintainers