In April 2019, I became one of the few content designers at the Government Digital Service (GDS) to move roles to become a technical writer.
I’m now starting my third year as a technical writer and joining the Central Digital and Data Office (CDDO). So it feels like a good opportunity to try to answer the question that people ask me a lot: what’s the difference between a content designer and a technical writer?
Who we write for
There are 13 technical writers at CDDO and GDS, and more across government. You can read a previous blog post on what it’s like being a technical writer.
Technical writers are made up of:
- documentation writers, who mostly write task-based documentation for civil servants building or using specific digital technology, like documentation for the code library behind the GOV.UK Design System
- guidance writers, who mostly write high-level guidance on best practice for civil servants on how to choose, build and use digital technology, like the Technology Code of Practice
We write specifically for technologists in government who need to do things with digital technology. That means our users include:
- developers
- technical architects
- senior technical decision makers
Content designers write more generally for pretty much everyone else who needs to get something done with government. For example at GDS, content designers write a huge range of content to help users do everything, from applying for a driving licence, to knowing what you can and cannot do during the coronavirus (COVID-19) lockdown, to getting a general understanding of GDS services like GOV.UK Pay.
As technical writers, we still make things better for the ultimate users of a public-facing service. However, we make that difference not by working directly on the service, but by helping technologists choose and use technology that makes services better, safer and more reliable.
One important caveat: ‘technical content’ has a wider definition outside CDDO and GDS. For example you’ll find technical content on GOV.UK for tax specialists, or for technicians doing an MOT. A content designer or a technical writer could work on technical content, depending on the department. But in this blog post, we’ll focus on digital technology.
How technical writers work
As technical writers, we’re user-centred design (UCD) people just like content designers. So to do our jobs, the skills we need and the way we work are almost exactly the same. We:
- write in concise, plain language to help users do a thing
- start with user needs and work closely with user researchers
- use data and evidence
- have great stakeholder management skills
- review each other’s content (2i)
- often work on high-level content strategy
Both roles are part of government’s Digital, Data and Technology Profession Capability Framework. You can compare the skills content designers need and the skills technical writers need to see how similar we are.
But as technical writers, we bring a very particular set of extra skills.
Love of learning and using digital technology
Technical writers usually bring more hands-on experience of technology than content designers need. We need to be really comfortable talking about, writing about and using technology.
We do not need to know everything about the technology we’re writing about. But it's important to have some understanding so we can talk comfortably with our subject matter experts, ask the right questions, and know when users may not be familiar with a term that a subject matter expert wants to use.
Diving into technology is particularly important for documentation writers like me. We write very technical instructions on using application programming interfaces (APIs) and include detailed code examples. One of the best ways to check what we write is to actually start up the technology and try it out ourselves.
It also helps to bring some knowledge of best practice in technology content. Our writing process is not very different to content designers: we use plain language, write short sentences, create a clear heading structure and so on. But technical writers need to understand and meet the needs of technologists, who expect and search for certain terms and headings.
Having an affinity for technology is also a big help with our next skill: using a ‘docs as code’ approach.
The ‘docs as code’ approach
We’ve blogged before about why documentation writers use a ‘docs as code’ approach. It’s about working in the same processes and tools as the technologists on our team - so technical writers and their subject matter experts can work on and iterate documentation collaboratively and nimbly.
So as documentation writers we need to be comfortable:
- using a text editor and plain text files rather than a content management system (CMS)
- working on content updates in Git commits and branches
- managing fact checks and reviews in GitHub
I had a lot to learn around these skills when I moved roles. It was nowhere near as scary as it seemed, and I love it all now. My setup feels so much more flexible and customisable than using a CMS, and - after getting my head around Git - it now feels easier to keep track of drafts and changes.
Guidance writers do not need to be familiar with Git and GitHub - they work in the Whitehall publisher CMS.
Strong engagement and advocacy
You do not have to look very hard to find the world’s developers crying out for better documentation. For example:
- in a 2020 industry survey by Postman, the biggest obstacle to using APIs by far was lack of documentation
- in the same Postman survey, fewer than 5% of people gave the API documentation they worked with a 9 out of 10 or higher
- in a 2020 survey by Smartbear, only 27% of organisations felt their API documentation was above average
There are quite a lot of tech writers at CDDO and GDS by industry standards. But - despite those stark industry survey results - it feels far less likely you’ll see a technical writer on a team than see a content designer. Content for citizens has come a long way since Sarah Richards wrote about the editorial approach for GOV.UK back in 2013, but I’d argue that content for technologists has some catching up to do.
When technical writers are on a team, we’re embedded with our extremely busy subject matter experts, who may not have worked directly with a UCD-based technical writer. So we need to work extra hard to engage and advocate. That means:
- making sure we’re involved as early as possible with new product features or new technology policy, so that the documentation or guidance keeps pace
- advocating for simple but appropriate language - we do not need to explain every technical term, but we let down our users if we assume that “everyone will know what that means”
- using interviews (chats with subject matter experts) and pair-writing to build relationships and show our value
- raising awareness of the need for accessible content and design
- finding ways to apply our UCD approach to help users in areas other than documentation - for example by helping developers on our teams shape API parameter names or error messages
Our subject matter experts are sometimes our users too. We often work on internal content that documents our teams’ own technology and processes, which brings its own challenges and unique ways of working.
We also need to work very closely with the content designers on our teams, to triage content requests, assign them to the right person and divide up the work. Sometimes that means working as a pair on writing content.
You can become a technical writer too
I got into technical writing because I’d always had a deep love for technology. I’ve been a passionate coder since my mum and dad got me a prized ZX Spectrum for my seventh Christmas in 1983. After joining GDS, I realised technical writing perfectly combined that passion with my love of content and writing. I’ve loved every minute of it.
Technical writers can come from lots of different backgrounds. The technical writer community includes former journalists, product managers and marketers.
As I mentioned briefly above - if you’re a content designer, it’s worth knowing that guidance writers in CDDO work in the Whitehall CMS and rarely need to write code examples or test technology. So it’s a slightly gentler step from content design than the documentation writing I do.
We’d love to talk to you if you’re interested in becoming a technical writer. We can also help if you’re a content designer who’s been asked to work on technical documentation, like API or data documentation.
You can read more about technical writing and get in touch with us on our technical writing community page.
1 comment
Comment by Rahel Bailie posted on
Thanks for this illuminating article.
The one thing I don't understand is why you'd have to use substandard tools (plain text files) when there are fit for purpose tools that allow you to manage content in sophisticated and efficient ways.
It is interesting to see how an operational model has been developed for this content genre.