https://gds.blog.gov.uk/2017/01/12/growing-technical-writing-across-government/

Growing technical writing across government

Technical writer using GitHub

As our director general said recently in a blog post, GDS is here to support, enable and assure government departments in their digital transformation. That means more listening, more collaboration and more sharing between us all.

In this spirit, I spent 5 days with the Ministry of Justice (MOJ) Digital and Technology team at the end of last year. I was invited over to the MOJ offices at Petty France to help them with work they are doing to establish a new specialism: technical writing.

The MOJ has deep experience in content design and digital engagement, but they recognised that technical writing needs a different set of skills. Technical writers must have a strong understanding of both technology and content so we can make technological things easy to understand. These skills are currently not widespread within government and, where they do exist, they often exist in isolation without much support.

Why do we need technical writing?

I’m one of 4 technical writers at GDS and our team is growing. Across government, departments and agencies are starting to recognise technical writing as an important skill – and, in some cases, recruit people to help with technical writing in a full-time role. But there’s still some misunderstanding about what technical writing is and how to improve it.

Development teams build and improve a lot of systems and services across government. Although we design services and systems to be as simple as possible, sometimes users need extra guidance and documentation. Clear technical guidance that’s readily accessible, such as API documentation, helps technology teams learn about best practice and share their experiences with each other, which can save a lot of time and duplicated effort.  

Spending 5 days with the MOJ

The MOJ has a lot of technology-related content that needs to be produced and made accessible so people across the department can work to the same standards and principles. The department also wants to share its technology best practice and experiences with the rest of government, through blog posts and other content. The technology and content design teams thought that a technical writer might be a useful addition to the department. They were keen for me to discover how much of their work actually required a technical writer and also how to get the best out of this potential new role.

I spent a week with the MOJ team to understand how they create, update and share technology policies and other content. I spent time with around 15 people across the department, including:

  • technical architects
  • security experts
  • intranet specialists
  • service managers
  • engagement teams

Based on our discussions, it was easy to see how a dedicated technical writer would be able to help create and organise that content, freeing technical architects and others to concentrate on digitally transforming the justice system. I collated my findings and advice into a content strategy, and now the MOJ is preparing to hire its first full-time technical writer.

How does technical writing work at GDS?

At GDS, every technical writer is embedded within a team. We move around depending on which teams need help and work with technology experts to produce accessible, accurate content. As I type this, I’m sat with a content designer to my left and a technical architect to my right. Content production is much easier if I’m able to ask both of them questions or advice.

We help teams like the Service Manual, registers, Common Technology Services and GOV.UK Verify, and help to run the Technology at GDS blog. We also get involved in other technology-related content, including technical job adverts, policies and writing for user interfaces.

What’s happening in other departments?

We’ve started working more closely with other departments to improve how they share technical knowledge with their users and within their organisations.

As well as my recent work with the MOJ, departments and agencies such as HMRC and Companies House are also heavily involved in technical writing. Both publish technical documentation for developers. For example, HMRC publishes API documentation on its API Developer Hub. As we continue to build services and systems across government, this type of content will only become more important. Government technology users should be able to rely on support and guidance to use that technology, especially if they didn’t build the technology themselves.

What’s next for technical writing in government?

As well as helping project teams with their documentation and publishing user guidance, technical writers across government are starting to evolve their role.

For example, at GDS we’re introducing writing guidance and standards for developer documentation. We’re also building a community to support anyone doing technical writing across government. You can find the community on the cross-government Slack at #technical-writing and on Basecamp. Comment below if you work within the UK government and you’d like an invitation to the Basecamp group.

GDS is recruiting for more technical writers. Visit the Civil Service jobs board to find out more and apply.

Follow Jen on Twitter, and don’t forget to sign up for email alerts.

1 comment

  1. Sarah Wood

    Hi Jen, can you send me an invitation to the Basecamp group. Thanks Sarah

    Link to this comment Reply

Leave a comment