Doctopus: How Ceph Documentation is Maintained & Evolved, & How You Can Contribute

on YouTube ↗25m

" summary

Ceph docs live in the repo doc/ tree with release-specific branches and a live selector, totaling about 178,000 lines across ~567 files; PRs trigger a full site build on Sphinx/ReadTheDocs and must pass before merge. Content covers architecture, ops, troubleshooting, developer references, and over 2,000+ config options. Sources are written in reStructuredText + Sphinx + a legacy Java diagram tool, backports are manual and fragile, translations and backport tooling remain unmet needs.

AI-written summary · about

" chapters (15)

1. 0:00Introduction to Ceph docs
2. 1:06Scope and scale of Ceph docs
3. 3:13Version-specific documentation
4. 4:40Tools used for documentation
5. 6:04When and how docs are updated
6. 7:49Importance of precise language
7. 10:40Fresh perspectives in docs
8. 11:42Command output and error messages
9. 13:50Encouraging new contributors
10. 17:19Reviewing documentation PRs
11. 18:23Simple ways to contribute
12. 19:27Future improvements and backports
13. 20:52AI and documentation challenges
14. 21:32Zack Dover’s impact on docs
15. 23:18Q&A and closing remarks

" related talks

• 29mContinuous Documentation: basics and advanced techniquesAnastasiia Tymoshchuk · PyCon Italia 2025
• 26mEvolution of Product DocumentationKartikeya Dwivedi, Jaromir Hradilek · DevConf.CZ 2020
• 32mBridge the Gap To OSS Adoption With Documentation: A Kubernetes StoryNatali Vlatko, Divya Mohan · KubeCon + CloudNativeCon Europe 2025
• 59mA kernel documentation updateJonathan Corbet · Linux Plumbers Conference 2023
• 47mEngineering DocumentationLorna Jane Mitchell · GOTO Copenhagen 2022
• 33mDocumentation for OpenPrinting projectsTill Kamppeter, Aveek Basu · Linux Plumbers Conference 2022
• 16mcod == docGilles Legoux · Devoxx France 2024
• 25mBuilding Docs like Code: Continuous Integration for DocumentationMason Egger · PyOhio 2019