Using documentation-driven development for GOV.UK Sign In

Documentation-driven development, or docs-driven development, means documenting what you’re trying to build before you build it. You’d use docs-driven development to write down things like the endpoints, responses and requests before you even start coding.

Essentially, instead of documenting your code, you code your documentation. It’s a low-cost way of prototyping your code.

Teams use docs-driven development for a number of reasons:

• interrogating the build at an early stage
• minimising silos or isolated work
• maintaining consistency

Interrogating the build at an early stage

Docs-driven development is a cheap and fast way to interrogate your design without wholly committing to its build. It’s important to know the team is creating the right thing in the right way without investing significant money, time and resources upfront to build the service and its design.

Crucially, docs-driven development isn’t a ‘Big Design Up Front’ approach to set every design decision. Instead, docs-driven development interrogates the top-level blueprint of what the team expects to build. The team can then use the documentation to:

• check the design works as expected and there’s no obvious gaps or inconsistencies
• check they’re building the right thing in the right way
• easily undo and rework the features or requests which don’t work

All these benefits save time and money overall. On top of this, docs-driven development allows for increased collaboration for a wider team to be involved and bounce ideas off each other in the early stages of building a service.

Minimising silos or isolated work

Docs-driven development means the team doesn’t work on features in isolation, but instead can see the build and how it works as a whole. Documenting the service and its features means it’s more straightforward to experiment with different architectural approaches and use the documentation to check how all the features worked in connection with other features.

This replaces creating individual features without seeing how they interact with each other. Minimising silos improves the end-user experience and can help inform wider design choices at an early stage before the product is too developed.

Maintaining consistency

Maintaining team consistency can be hard, especially when work spans multiple teams. Documenting how a product or service works means you can use the documentation as the single source of truth. This improves consistency and means the code will always be up to date.

Realising docs-driven development potential

In March 2021, GDS's One Login for Government programme started developing the authentication component for its new product that will make it easier for users to sign in, prove their identity and access government services. This product is currently called GOV.UK Sign In.

The authentication component will sit alongside GOV.UK Sign In’s identity verification component, which has an initial release later this month. Authentication needed to pave the way and set up practices and workflows which identity could integrate with at a later stage.

The authentication team chose to use docs-driven development because:

• we started from a relatively blank piece of paper without legacy technology or documentation
• the team was in the early days of conceptualising the technology we were going to use to build the authentication component 
• we had subject matter experts who had worked on authentication solutions before, for example NHS Login
• we had a technical writer dedicated to writing user-led technical documentation

Mapping the technical architecture and user needs

We started with using subject matter experts’ previous knowledge of authentication solutions to work out the architecture for how the technology would work, the type of requests, responses and endpoints we would use, and the technical flow.

The technical writer and subject matter expert mapped this flow to users’ tasks. This helped with checking we weren’t flooding users with unneeded information about how the service worked in the backend, just what they needed to do to get it working.

We took these tasks and created a task-based top-level hierarchy of pages, for example: ‘Generate a key pair’ or ‘Choose the level of authentication for your service’. Using this approach helped interrogate our information architecture before we got too deep in writing the documentation.

We shared the documentation plan and technical architecture for the service build with the wider team. This meant we all had an understanding of what the build would look like and could contribute to any iterations.

Writing and developing the authentication component

The technical writer began pair-writing the technical documentation with the subject matter expert, prioritising the pages based on:

• whether the team had made the dependent technical decisions yet
• how crucial the page was to the overall flow
• estimated length of page

Referring to the OpenID Connect technical specification and writing the technical documentation became the first step in holding conversations for what features the authentication component would support. The developers then used the documentation to help build the endpoints, requests and responses. The technical writer could work with user researchers to regularly test the technical documentation and iterate based on changing user needs and feedback.

Maintaining docs-driven development beyond launch

Docs-driven development worked well before launch when the landscape was open, but we needed to maintain this approach through to launch and beyond.

To do this, the team instilled a culture to update the documentation as standard when building a feature or fixing a bug.

Having a technical writer dedicated to maintaining docs-driven development lifted the documentation load off the developers. The technical writer and developers could work in tandem with the developers building, while the technical writer could focus on writing.

Writing or updating documentation and testing the documentation is a success criteria for our features. This has helped create a user-led and interrogated build, which helps improve the service quality overall.

What’s next?

The authentication team continues to blend feature development with writing technical documentation, and our technical documentation for GOV.UK Sign In is now public.

The team is now working on building the identity component. The identity component will use docs-driven development to help build their technology.

GOV.UK Sign In is currently inviting beta partners for authentication. You can find out more about our selection process and GOV.UK Sign In on our recent blog post.

If you think your team would be a good fit to be a beta partner please register your interest.