So often, technical documentation has two audiences — internal and external users. And when your a government, your external users can potentially include all citizens. So how can you prioritize it all?
Rosalie Marshall is the lead tech writer at the U.K.’s Government Digital Service (GDS), part of a cabinet office tasked with the digital transformation of government “to optimize developer documentation and how we’re making it consistent throughout GDS and hopefully the wide government.”
The British government is heavily investing in documentation. Marshall was the first technical writer a year and a half ago, and now the team has grown to nine, as they build and document a Government as a Platform, defined as:
“We’re creating a set of shared components, service designs, platforms, data and hosting, that every government service can use. This frees up teams to spend their time designing user-centric services rather than starting from scratch, so services become easier to create and cheaper to run.”
The purpose is to develop products that you can reuse by the rest of the government. It’s a way to increase efficiency and reform and to cut costs, implemented as a part of the whole government’s budgeting initiative.
This includes two main segments:
- Gov.UK Verify — to enable individuals to prove their identity online and to access government services securely and safely.
- Gov.UK Notify — to notify citizens.
Documentation became the solution to bring together the websites and services of an entire government, so developers can understand a complex system via a series of questions and tasks, so they can easily integrate and reuse products.
Please write great docs. It's your users first impression of you and your product.
— Ashley McNamara (@ashleymcnamara) July 27, 2017
Success of the project has been defined as “developers need to be able to pick it up easily [and it has to] encourage more code sharing across government and use of open source software.”
And as GDS wants to open up to more citizen developers, this documentation has to work not only internally but externally too.
Begin with Questions
Like all good documentation, the process began with research. First, the design team asked 30 developers and technical architects currently working with pieces of the complex GDS what they thought of all the existing documentation and what they wanted. Marshall and her team requested an itinerary of all the documentation they interacted with in a week.
Next, the team presented their test subjects with a mix of different styles of API documentation, both internally and externally like that of the World Bank.
At the recent APItheDocs conference in London, Marshall said: “I got told it had to be very formal because developers only like formal content, so we put that to the test.”
They offered the various doc examples on cards and facilitated them sorting them for priorities. Finally, the team asked companies known for their documentation, like Stripe and GoCardless, for advice.
Marshall said they discovered:
- Good docs need to communicate concepts and help you get stuff done.
- Developers consume content differently to citizens but they still want friendly content, to be talked to, to have friendly content. They wanted the same style of content used for the public (i.e. not too formal).
The user documentation needs were as follows:
- “I need to know documentation is up to date — reading it all, not missing out on stuff.” They wanted a label on top of when docs were last updated. Marshall said they could do that easily with automation tools like Swagger.
- Developers want to know if the version they’re reading is the right one, which meant a need for versioning automation.
- The ability to search and scan the docs.
- A table of contents.
- Blocks of code to be color-coded so they stand out.
- Working examples of frontend code embedded in documentation.
- To link directly to parts of pages to bookmark and share.
In the end, they realized they were creating documentation for two different audiences:
- Citizens who want help answering questions and accomplishing single tasks
- Developers who have to understand a complex system
If You Can’t Find It, Build It Yourself
Marshall said they originally chose Gelato as a developer portal because it presented the documentation nicely and there was also an API explorer developers really liked.
“But it was just a short-term solution — [it] didn’t have versioning, we weren’t in control and had to ask for help,” she said.
In the end, they realized they needed to think about how to build their own documentation tool. They wanted it to look like Gov.UK and to be hosted on it, so it could be easily found by developers. They needed a tool that could handle both API documentation and technical manuals.
So they created GovSpeak from scratch, an extension library that Marshall described as similar to Markdown, but with numbered lists and example callouts. It also has automated testing of code samples and a consistent look for all documentation.
“Be specific about developer user needs and prioritize them.” — Rosalie Marshall
Now with a Plan, How’s It Going?
A minimal viable product of GovSpeak is available via open source on GitHub. This is just the first iteration of the new documentation.
Marshall said, “The tech writer user needs aren’t incorporated yet, but developers are really enjoying it.”
Next step is to get an API explorer and to switch payments over to the new platform. Their goal is to base it around OpenAPI Specification. They also want to create a slackbot for documentation reviews, and to move all the information still in Gelato over to GovSpeak.
The challenge continues to be prioritizing what next to build into their tool.
“We have come a long way, but, at the same time, there are lots of other priorities that GDS is committed to besides building an API doc tool,” Marshall concluded her talk.
The next goal is to keep up with new additions to the tool while making sure high-quality documentation is being created and continually updated.
The post Why Writing Great Docs Matters So Much to the UK’s Government Digital Service appeared first on The New Stack.