Building Docs like Code: Continuous Integration for Documentation
summary
Advocates keeping documentation in the same repo and building and publishing a static site on every commit, with automated link checks and doctests so code examples stay correct. Uses MkDocs and Sphinx for output, a cookiecutter starter, Travis CI (Docker + Makefile + pipenv) and publishes to GitHub Pages. The author ships a cookiecutter pipeline that auto-builds and auto-publishes; it works in demos and cut support load dramatically — one team reports ~98% of support queries answered by docs.
AI-written summary · about
chapters (21)
- 0:00Start
- 0:43Who is this talk for?
- 1:15A Common Approach to Documentation
- 2:17Issues with This Approach
- 3:49Why Do Developers Dislike Writing Documentation?
- 4:13The Real Issue
- 5:13What If We Treat the Docs Like Code?
- 5:49What Do We Mean When We Say "Treat Docs Like Code"?
- 6:23What Do We Gain From This?
- 9:12Case Study
- 10:22How Does This Change the Workflow?
- 11:24What is Continuous Integration and Continuous Deployment (CI/CD)?
- 12:17What Does This Mean for Docs?
- 14:05Types of Documentation
- 16:22Documentation Tools - Mkdocs
- 17:07Mkdocs - Extensions - UML
- 17:59Documentation Tools - Sphinx
- 18:38Sphinx - Documentation Testing
- 19:18Documentation Tools - ronn
- 20:09My Solution
- 27:01Final Thoughts
related talks
35mBuilding Docs like Code: Continuous Integration for Documentation
25mBuilding Docs like Code: Continuous Integration for Documentation
23mTreating Documentation like Code: a Practical Account
42mEngineering Documentation
29mContinuous Documentation: basics and advanced techniques
19mWhere Docs, Cloud-hosted Interactive Tutorials and CI Testing Intersect
59mTransforming your Documentation Process
45mDocs as Code Fix a poor documentation culture in your organization