As we traverse an increasingly technological age, the role of documentation has become more important than ever. Documentation helps people understand technology and how to use it, it encompasses everything from technical manuals and user guides, online help systems to API documentation, release notes and readme files.
Inherent to these documents is the role of the documentation writer: a career that takes on various job title terms depending on preference, the most common being technical writer or documentarian. This article explores the role of the technical writer - what they do, how to enter the field, and what kind of skills and attributes are required with personal perspective from three people working in documentation.
Why Are Documentation Writers Needed?
Whilst documentarians sometimes work hand in hand with developers, it stands that the role is (and needs to be) distinct from that of a developer. Technical writer Jacquie Samuels believes that documentation requires content written from the user’s perspective, takes the user’s point of view, and strips away inadvertent assumptions a developer can make, commenting:
“A big shift needs to occur when writing usable content. A developer’s viewpoint when writing documentation is “this is my product; here’s how to use its features.” A technical writer, however, creates content thinking “hello user, here is how you’ll be doing the things you want to do with this product.”
Documentation is a key part of customer problem solving, particularly on creating a knowledge base, where writing guides a customer towards a solution. In these scenarios, the goal is to create documentation so good that your customers don’t need to contact your support team. The way you support your product is as important as the product itself.
How to Get Into Documentation
Technical writers have a wide variety of backgrounds and can work in an extensive range of industries including information technology, defense, aerospace, retail, banking and finance, mobile telecommunications, and pharmaceuticals. There is, however, no fixed entry route.
DZone Zone Leader and writer Chris Ward, explained that a computer science degree and a job in coding lead to a career in documentation as “I used to be a coder and started contributing documentation at code Sprints for open source projects because it was an easy thing to get started with and I realised I was better at it than coding and I could actually turn it into a job.”
For Samuel Wright, a degree in theoretical physics and “the experience of a few really uninteresting jobs” meant he started to look for a job that combined technology, people, and language:
“I got my first job based mostly on writing samples of music reviews. After writing a couple of manuals for a machine that tested artificial knees I decided to focus on developer documentation. The more complex the documentation the fewer people there are that can write it well, and for someone with my mindset, the more interesting it gets.”
The career pursuits of friends can also provide exposure to new career opportunities. Beth Aitman studied history at university:
“But a lot of my friends were mathematicians and computer scientists, and they talked a lot about programming. Eventually, I decided to find out what the fuss was about, taught myself a bit of Java, and got quite into it… I applied for a couple of entry-level developer jobs, jobs that would accept applicants with no professional programming experience. I didn't get any of them - most of them were pretty surprised to see someone who didn't do a STEM degree. But one of the companies thought I might have some aptitude, and very kindly asked if I wanted to join in the C# correspondence course they ran for their new starters. I learned a lot from that course - I'm still really grateful for that experience.
So I reached the end of my final year and started going to careers fairs again. I had my opening line - 'I'm a historian who's interested in programming, are you interested in me?' Most companies said no, but one said yes - they were looking for grads who understood technology and knew how to communicate! That was the first time I'd ever heard of the job title 'technical writer,' and it sounded like a perfect mix of the things I was interested in.
I applied for the job at Improbable.io, got it, and absolutely loved it. It couldn't have been a better fit for me.”
What Kind of Attributes Are Required?
Wright explains that an enthusiasm towards learning is a key component of documentation work:
“You have to enjoy learning new things all the time and be able to get your head around complex information. You have to be able to think about the person using your documentation, and understand what they want to do, and why. The actual writing is a smaller part of the job than most people think, and definitely one that improves with practice.”
Ward agrees that writing is something that gets easier over time, especially if you are with a company for a period of time and understand their style guide, terminology, etc. He also notes that you have to be confident in talking to developers, amending and editing documentation -sometimes at the last minute prior to release. All interviewees agree that an ability to time manage and prioritize is crucial.
Where You Sit Matters
The status and positioning of a technical writer may differ in a company, especially if you are the only one in the role, and you may find yourself sitting with the developers or the marketers depending on the organizational flow of the workplace. This can lead to different experiences in different workplaces. Ward notes that in some companies, documentation is considered less valuable than coding: “There's a lot of lip service paid to documentation, saying it's important but most of the time devs are usually king and no matter how hard you push to make something happen, usability and understandability suffers.”
Because of this, a good working relationship with the developers, technical team, and CTO are imperative. Aitman comments that “developers I work with ask for my input on what they're writing a lot, which is always a good sign.”
Training and Professional Development
As there’s no official entry level into technical writing, there are no official qualifications. Ward comments:
“I wouldn’t probably bother with a training course. Look for open source projects to contribute to because documentation is usually lacking, you could either have a background in writing or development, people in the sector from both, both bring different things to it. I know plenty of people who don’t come from technical backgrounds at all and they’re fine. I would also say its one of those sorts of roles that people don’t always advertise so if you are interested in a company and you think their documentation needs some work then just apply.”
Aitman notes that she hasn’t done any specific training with all her learnings on the job, “with colleagues and customers providing feedback to help me improve.”
Solidarity Amongst Writers
The Institute of Scientific and Technical Communications (ISTC) based in the UK provides a mentoring scheme, where junior members receive the support, advice, guidance, and encouragement of a more senior member of the ISTC. In the US and throughout Europe there’s Write the Docs, a community of documentarians who hold two annual conferences in Europe and the US, regular meetups and events, and resources like mailing lists and Slack channels.
Wright suggests, “If you want to practice/get experience, find some writing to do that solves a problem for people. Know your audience, work out how to solve the problem - then test it to see if what you've done works, and iterate and improve.”
Work experience is also a great opportunity for learning about the role of documentation. Aitman suggests:
“If you want to get work experience - try asking companies, even if they don't say they offer it. My old company ran software development internships, but not a tech writing one, until someone emailed us to ask if we could give her some work experience. As we already had an internship system set up, it was pretty easy for us to decide we could offer a tech writing internship (paid, of course!) and it went really well. So you never know - it's always worth asking."
All three interviews exalt the benefits of networking with like minding people, especially through attending conferences and meetups. According to Aitman:
“They’re great for inspiring you to think about the work in a new way. It's wonderful to be surrounded by people who care about the same things I do. I'd hugely recommend Write the Docs to anyone interested in documentation. I always leave inspired, and I've learned writing tips there that I still use most days.”