Margaret Eker, Jennifer Rondeau - Docs as Code: The Missing Manual

Docs as code is less about changing what documentation is written in and more about making documentation delivery behave like software delivery: planned, iterated, tested, reviewed, and deployed through the same fast feedback loops. The core promise is tighter sync between documentation and code—achieved by storing docs alongside code, building them with static site generators or doc generators, and using continuous integration/deployment so drafts can be rendered quickly and updates can ship without waiting for a big release cycle.

A major gap sits underneath that promise: many teams treat documentation as a single “light” line item in release planning. That works for small fixes, but it collapses when scope expands—new features, cross-feature impacts, or entirely new products that require help systems or large manuals on a compressed timeline. The missing manual framing pushes teams to map the full documentation workflow the way they already map code workflows: scope documentation work from the start, design the content types and information architecture needed for reference, concept, task, narratives, and other topic formats, and plan deployment models (static publishing versus integration into product surfaces).

In practice, the workflow becomes iterative and environment-driven. Instead of writing once and publishing later, teams create drafts in a repository, commit changes, and rely on a docs-as-code development environment to build and deploy to staging so contributors can see rendered output almost immediately. That requires more than tooling: content models and templates must exist, contributor onboarding and cross-training must be planned, and review guidelines need to be explicit so multiple stakeholders can evaluate drafts consistently.

Quality assurance is where the “missing manual” idea sharpens. Code teams separate testing into unit, integration, regression, and acceptance tests; documentation teams often stop at manual review plus basic syntax/structure checks from linters. The argument here is that documentation testing can be expanded beyond “does it parse?” toward functional coverage—such as ensuring release notes for a bug fix get carried forward into subsequent releases, or that documented workarounds remain correct after changes. Automation can handle much of the repeatable checking (linters and other test harnesses), leaving humans to focus on the hardest acceptance-level questions at the product and documentation level.

The talk closes with a practical checklist of what makes docs as code succeed: align project planning with the GitHub workflow, establish review workflows and guidelines, set up a shared development environment with continuous integration and delivery, and invest in communication across teams during migration. Tools speed collaboration, but they don’t guarantee it. Without shared planning and ongoing coordination, teams still struggle—described as a difficult migration from docbook/XML and Jenkins to a newer system—because adoption depends on people using the same terms, the same processes, and the same feedback loops. The takeaway is straightforward: docs as code improves the odds of keeping documentation in sync with code, but only a complete, planned, iterative workflow turns that odds into reliable delivery.