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 live.
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.
Would your government service like to become an early adopter of GOV.UK Sign In? If you’d like to participate in our private beta, register your interest via our product page.
4 comments
Comment by Adam posted on
I'm not sure if this is the right place to comment, but is (or could/should) this work be linked with the Digital Identity Foundation (https://identity.foundation/) which is developing an open, standards-based identity ecosystem - W3C Verifiable Credentials, etc.?
Comment by The GDS Team posted on
Hi Adam,
Thanks for getting in touch. We participate in the W3C Credentials Community Group and will continue to engage with them as our private beta develops.
Thanks,
The GDS Team
Comment by Max posted on
This doc driven development sounds interesting. Does a Business Analyst or Product Owner play a part in this process. If so what do they do?
Comment by The GDS Team posted on
Hi Max,
It’s a good question. A Business Analyst (BA) or Product Owner (PO) wouldn’t play a direct part in writing the documentation when doing docs-driven development, but they would be involved in other ways.
For example, the PO would define the priority of the technical features you're documenting, and the BA would make sure the developers have the correct information within those tickets to actually build them. On top of this, if you’re writing documentation when building a service and realise a particular functionality or request might have a wider impact on the service flow, you could raise this with a BA or PO. This would help make sure the overall service design and user experience of the service is consistent.
For GOV.UK Sign In we’re using OpenID Connect, which is a well understood open standard. If the service being developed isn’t using such a well understood open standard, BAs and POs would play an even more critical role.
Thanks,
The GDS Team