Jen Lambourne - The UK government meets docs as code

The UK government’s Government Digital Service (GDS) turned technical documentation into “docs as code,” but the real breakthrough wasn’t the tooling—it was the sequence of decisions that made documentation easier to find, easier to update, and cheaper to support. After years of inconsistent docs scattered across PDFs, emails, and multiple locations, GDS used software-development workflows (version control, pull requests, automated builds) to bring documentation under the same discipline as the products it describes. The payoff: users found answers faster, support tickets dropped, and developers could contribute without being blocked by proprietary publishing setups.

The journey began with hard user research showing documentation performance was “extremely poor”: content was inconsistent, hard to locate, sometimes not published online at all, and difficult for technical writers and developers to keep synchronized with agile product changes. With technical writing still new inside GDS, teams were also wasting time training each other on different tools. Developers wanted to help improve docs, but their contributions were trapped behind closed or fragmented systems—like proprietary tools, isolated repositories, or PDFs with no single source of truth.

A first attempt at docs as code started small, then faced the reality of government scale and constraints. Hiring was frozen, so GDS leaned on the broader developer community for help—using informal incentives and strong demand from people who had felt the pain firsthand. A business case then had to justify where the work would live. GDS ultimately assigned the effort to a team without external-facing docs, because that team was building a cross-government design system and needed documentation that could fit across products rather than be tailored per service.

Tooling decisions followed. GDS chose GitHub for repository hosting (matching how developers already worked) and organized docs under an open GitHub organization called alpha gov. For static site generation, the team initially considered popular options like Jekyll and Hugo, but switched away from Hugo due to limited Go expertise and the need for maintainable extensibility. They selected Middleman (Ruby-based) instead, leveraging GDS’s Ruby experience and templating needs.

Content architecture then became the next major fork. User research for API documentation pushed GDS toward a single-page reference layout—optimized for Ctrl+F—while other information (like authentication and support) still required different placement once multi-page navigation became necessary. GDS also split repositories: internal-facing docs lived alongside product code, while end-user docs moved into separate repositories to simplify findability and access control.

The team hit another wall when legacy documentation written in reStructuredText proved too complex to convert cleanly. Rather than forcing tooling to compensate, GDS treated the problem as a content issue—simplifying and rewriting bloated, outdated material in plain English before converting it to Markdown. Deployment started manually (a short-term compromise) but the long-term goal remained automation through continuous integration and deployment.

As contributions scaled, GDS added governance: pull requests required specific reviewers, technical writers or lead developers had to approve changes, and GitHub labels indicated the review path. Slack-based nudging followed, including an automated “nag” bot to keep documentation reviews moving.

Later, accessibility regulations arriving in September 2019 forced urgent template updates with weeks to implement—while half the technical writing team was in Prague. With no time and no cash, GDS again turned to developer support, using developers’ protected time (20% time) to keep the documentation system compliant.

By the end, GDS reported measurable benefits: happier users who could find information more easily, reduced support costs and tickets, and developers who could contribute faster—freeing them to focus on writing and improving docs rather than wrestling with tooling and training. The overall lesson was that docs as code is a long chain of interlocking choices, and success depends on aligning tooling, content, workflow, and review culture—not just adopting a static site generator or a repository format.