WtD Prague: Docs as code and the UK government

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Jen Lambourne’s talk was titled, “The UK government meets docs as code”. Jen is head of technical writing at Government Digital Service (GDS) in London. Her team manages all their docs (internal and external-facing) using docs as code.

Docs as code is the practice of applying software development tools and processes to technical documentation.

At first glance the processes of docs and code look similar:

• Docs: Write -> edit -> review -> publish
• Code: Write -> review -> test -> deploy

Jen’s presentation showed us how the above process flows are actually not that similar. You’re faced with plenty of unexpected scenarios, and you need to make decisions in those situations.

User research

User research showed the docs were performing poorly.

There were no technical writers yet. A new tech writing team was in the making. Developers wanted to contribute to the docs, but could not. The docs used proprietary tools and PDFs for which the original source was lost.

Experimentation

The team ran an experiment to see if the docs as code tooling would work for them. Initial results were encouraging.

But scaling is important in a project the size of a UK government department. And funding is a problem always.

Getting the tooling

Faced with the decision on whether to hire a tech writer who knows code, or to beg help from an in-house engineering team, Jen’s team chose to ask for help from an engineering team. They traded skills when asking for help: if you help us with git merging, we’ll help you with how to write a blog post.

Repository

They chose GitHub as the location for their docs source. That’s where the developers store their code.

Handling stakeholder feedback

When stakeholders became anxious and asked why the tech writers weren’t focusing on the content rather than the tools, Jen’s team had to choose whether to refocus on updating content, or finding out more about the stakeholder’s concerns. They chose the latter, and showed the stakeholder how an improved tool set would lead to improved content in the long run.

Static site generator

Jen’s team chose Hugo over Jekyll, because Hugo has plenty of templates. But soon they discovered that Hugo wasn’t right for them because it’s written in Go and GDS doesn’t have much experience in Go.

So they went back to the drawing board, reassessed their options, and chose Middleman (written in Ruby, which GDS has experience in).

Doc repository

Should the docs be in the same repository as the code, or in a separate repository? Jen’s team chose a separate repo for the user-facing docs, while internal docs go in the same repo as the code.

Separate repos as best for findability and access control.

Continuous or manual builds

At first the team decided to trigger the docs build manually, but later moved to continuous integration (CI). Jen recommends CI.

More decisions

Jen talked us through many other decisions that faced the content team. For example, do you choose single- or multi-page design, do you convert docs that are in other formats, do you do the conversion by script or by hand, do you use a linter or rely on reviews to enforce style, and more.

There’s still work to be done, but even at this stage the team has seen plenty of benefits. Developers contribute to the docs, support tickets and complaints are way down, and the docs processes is usable.

My takeaway: automation is key, but it takes time and you may need to reverse earlier decisions to work better with automation.

Thank you Jen, this was an amusing and informative story about docs as code.