You may have heard, rule number one for us at Government Digital Service (GDS) is: “always start with user needs”. We do user research. Lots of it. GOV.UK Verify recently completed their 100th round of user research, and they’re not stopping there.
Who are our users?
At GDS, when we think of users we tend to think of end users of a product or service. For GOV.UK Verify, that means members of the public who need to verify their identity on line so they can access government services.
But there are other users who may not be so visible - for example, developers in government departments who want to integrate their service with GOV.UK Verify or host their app on Government as a Platform (GaaP). These users are just as important to us. After all, if developers in government departments don’t know how to integrate their service with GOV.UK Verify or host their app on GaaP, the end users won’t have a service to interact with.
Asking questions
That’s why we have a small team of technical writers at GDS. We’re part of the content community, but we write technical content for technical people within government.
We’re embedded in multi-disciplinary teams, and like content designers we work closely with subject experts who help us develop content. We need to ask questions about how the thing works, find out how people use it and review our understanding as we go along. Subject experts can be developers, technical architects, support experts or anyone who has specialist knowledge of the thing we’re writing about.
When we ask questions, subject experts sometimes tell us “developers know that already so there’s no need to explain it”. Subject experts provide valuable information about what our users may know already and what we need to explain, but they sometimes make logical jumps and assumptions that are not obvious to the non-expert. So we also use feedback from user research and other team members to help build up an understanding of our users’ needs.
For example, when integrating with GOV.UK Verify, one of the things developers in government departments need to do is generate self-signed certificates for the Security Assertion Markup Language (SAML) compliance tool. When we were discussing what to put in the technical guide, our subject experts said information on certificates was not needed as developers will already know how to do this. But user research showed that developers were confused about certificates. Also, engagement leads said that several developers had asked how to generate self-signed certificates.
We clearly needed to provide some guidance, but we didn’t want to explain a process that’s already publicly available. We try to keep our documentation as concise as possible and provide a single source of truth, so users don’t end up with several different descriptions of the same procedure. So we just put a link in the technical guide to a site where developers can find out how to generate self-signed certificates.
Research shows that the second biggest challenge for developers is poor documentation. At GDS we take the needs of developers seriously. Technical writers collaborate with technical experts, user researchers and other team members to provide documentation to meet developers’ needs.
If you’re a developer who uses government documentation, we'd love to hear how we can improve it.
If you write developer documentation for government services, please join our Basecamp community.
You can sign up now for email updates from this blog or subscribe to the feed.
If this sounds like a good place to work, take a look at Working for GDS - we're usually in search of talented people to come and join the team.
