Become a tech writer: a quickstart guide
In the spirit of a code quickstart, this is a quick, opinionated, description of one possible tech writing learning path.
Every so often, someone joins the Write the Docs Slack, and asks a ton of questions around getting started in tech writing (or retraining with in-demand tech writer skills). This post captures my favourite resources, my perspective on key skills, and an outline learning path. In the spirit of a code quickstart, it doesn't aim to be comprehensive, and it's highly opinionated. It is biased towards the technical end of software documentation.
The properly quick quickstart
- Join Write the Docs, a community of documentarians. Dive into the Slack, check out their website resources, and attend a meetup or conference.
- Buy or borrow Docs for Developers. This is a good all-round introduction to writing software docs. You may not need much more than this.
And then get started on four learning areas:
- Writing: Write something (a short how-to or tutorial, on any topic) and copy it into Hemingway. See how low you can get your reading grade.
- Structure: Watch The four kinds of documentation. This will make you start thinking about the functions and structures of documentation.
- Tooling and processes: Read Docs Like Code. You will learn a valuable (and in-demand) approach to docs production and tooling.
- Key technical skills: Learn git. If you're going to work in a docs-like-cdoe setup, you'll need this. You can also set up your portfolio and demonstrate your ongoing learning on GitHub.
The longer quickstart
What is a tech writer?
A technical writer (or technical author) produces material to help users achieve their goals. This can be anything from API documentation to help developers use a service, to in-app help to support new product users, to IKEA furniture manuals. As the name implies, tech writers primarily produce written material, but many also use screenshots, videos, diagrams and so on.
So you want to be a tech writer? What next?
Stop and think. Ask yourself the following:
- What areas do you already have expertise in? For example, if you're a developer, you may find it easier to switch to documenting code than writing vehicle maintenance manuals.
- What subjects do you want to write about? You may be a developer who's sick of code, and thinks writing about vehicle maintenance would be a refreshing change.
If your answers to the first two questions are very different, keep in mind that in addition to tech writing skills, you'll also need to learn a little about the domain you're documenting. Tech writers don't have to be experts, but it helps to have some familiarity with your topic.
- What type of job do you want, and how do you want to work? Are you happier as an employee or freelance, on-site or remote? What type of company you want to work for? Although I love freelancing, I undoubtedly benefited from time as an employee.
Defining your answers to those three questions will help focus your learning, and narrow your job search.
Writing
Technical writing has its own conventions and rules. It is a restricted, simplified use of language, and takes practice.
- Use Hemingway to quickly check your writing and train yourself in better habits.
- Watch The four kinds of documentation. This will make you start thinking about the functions and structures of documentation. You can learn more about the framework in the talk on Diátaxis.
- Read the first section of Every Page is Page One. This offers insights into how people find information in the internet age.
Tooling
- Read Docs Like Code to learn a valuable (and in-demand) approach to docs production and tooling.
- Learn git.
- Pick an SSG (static site generator) and play with it. Build a blog, a portfolio site, or whatever takes your fancy. If you are unsure which SSG to choose, MkDocs with the Material theme is designed for documentation, and a great place to start.
Trying out a static site generator may help you identify other gaps in your tech and tooling skills.
Be prepared to do something else first
Getting into tech writing can be hard. Many people do something else first, with a writing element to it, and get into tech writing that way. This is especially helpful if you're not already working in tech: it can be easier to get your first tech job in a different field then progress into tech writing. If you're already in a tech job, see if you can add tech writing elements to it.
Some good options:
- Support: quite a few tech writers start in support, get fed up of repeating themselves, and start writing docs to solve their own and their users' headaches.
- Marketing: marketing writing and tech writing have overlaps, and there are many marketing specialisms that can include a writing element - in particular, the technical end of content marketing.
- Developer: many tech writing jobs, especially in startups, ask for tech skills. Starting as a developer gives you evidence of strong tech skills. And if you're a dev who's willing to write documentation, that's an awesome combination.
Don't stop learning
In addition to writing and tooling skills, you will need:
- Professional skills, such as interview techniques and wage negotiation.
- Project management techniques, including planning and tracking work, and integrating with other teams.
- Domain-specific knowledge, such as a programming language, or particular terminology.
And, crucially, you need to keep these skills up to date. Popular tools and methodologies change. Even style conventions evolve. Don't stop learning.