Getting started in technical writing

If you are thinking about working as a technical writer or are curious about the profession, this blog post will hopefully give you some useful tips on getting started. I'll explain what technical writing is, how it differs from other types of writing, and what sort of skills you need to succeed.

What is a technical writer?

A technical writer is a person who creates information. Usually, this is in the form of online help, web pages, customer support content, videos, tutorials, and the good old-fashioned instruction manual. Typically, we create long form content, such as user guides that explain concepts in simple terms and include how-to instructions.

Good technical writers take a user-centered approach. This means they write from the end-user's perspective, helping them to achieve their goals quickly and safely. This requires some user research, a curious mind, and empathy for the end user. They also write using clear, simple language where the goal is to make the message easy to understand. Technical writing is not prose and should not have "personality", it is simple and factual.

As technical writers approach content from the user's perspective, they often have skills that are also used in other user-centred professions, such as training, customer support, UX writing and content design.

What's the difference between a technical writer and a technical copywriter?

A technical writer is focused on helping the user perform a task or understand a concept. They are not persuading the user to do anything, they are only trying to help them. Technical copywriters are people who specialise in writing marketing copy for technical products and services. So their role is different as they need to capture the reader's attention, convince them of the benefits of the product, and compel them to take action, whether that's buy the product, get in touch, or order a demo.

Technical copywriting is part of the pre-sale effort to win customers. Technical writing is part of the post-sale effort to support customers and help them get the most from the product.

What's the difference between a technical writer and a UX writer?

UX writers are specialists in creating user-experience copy, often called "microcopy". It is the content you see on the product itself, such as the names of fields on a form and the text that explains what the field is for. It is usually short text, but has to be carefully crafted so that it provides the right information and makes the right impact. If you've used an app on a smart phone, you've seen UX copy at work - all the on-screen labels, text descriptions, and information is likely the work of a UX writer.

Most technical writers that I know have also done some UX writing work. This is usually as a result of documenting a beta version of a product and seeing that developers have given things obscure or confusing names that user's are unlikely to understand. As a technical writer creates user-centered content, they also know what the user needs from on-screen/in-product information.

But it would be wrong to suggest that all technical writers can do UX writing well. That's not the case, and UX writers often need more copywriting skills. For example, an app may need to promote other products or encourage the user to buy add-ons. Those selling skills require a different approach and the writer may need to consider tone and voice a lot more than a technical writer generally would.

‍

What's the difference between a technical writer and a content designer?

Content designers are people who design information that's usually aimed at providing services to the general public. Traditionally, you will find them employed in government departments, charities, and similar organisations. But these days, you are just as likely to find them in commercial organisations, where they create information about products and services, just like a technical writer would.

When the goal is to produce user-centered information about a product or service, I don't think there's a great deal of difference between a technical writer and a content designer. The working practices may vary, but both will research the user needs and create content that meets those needs. The goal is to help the end user.

But content designers often have to create content that retrieves information from the user. For example, a content designer would create the online forms you need to apply for housing benefit online or apply for a replacement driving licence. This requires an understanding of best practice for designing forms and asking for personal information. You'll also find content designers have to be very aware of accessibility requirements.

In my opinion, technical writers, content designers, and UX writers are all different types of information designer. We all create information for slightly different needs, and inevitably, there's some cross-over.

What's the difference between a technical writer and a technical author?

Nothing! Technical author is often used in the UK and sometimes Europe and Australia, whereas technical writer is more common in the USA and Canada. They are both the same job.

What is an API technical writer?

An API technical writer or SDK technical writer is someone who specialises in creating documentation for developers. These people design information that tells developers how to program their systems so that they can interact with other systems. As API technical writers document code, it is often a requirement (or preference) that these writers have a good understanding of the code they are writing about. That's not always the case, as good technical writing is often about asking the right questions rather than having technical knowledge, but it is something you'll likely see on job ads.

In some organisations, documenting code is the distinction between technical writers and content designers. I believe that's the case in the UK government, where technical writers document the code and content designers create the public-facing information pages, forms, and the like.

Do you need a technical background to be a technical writer?

In a previous blog post, I argued that you don't need a technical background. In fact, it can hinder you if you are writing for a novice or intermediate audience, as the amount of knowledge you have makes it more difficult to appreciate their position. When writing for these audiences, I think the most important skills you need are an ability to explain complex things in simple terms and an understanding of how to find out what the user needs. With those, you can at least organise and present the information the user needs, in terms they can understand.

But ...

There are some types of technical writing where a technical background will help, and these tend to be where you are writing for experts. API docs is one such area, as it is going to be much easier to document code if you understand the code yourself and don't have to rely on developers to explain every detail. Personally, I've found it challenging to document products that need to be wired by electricians, as there can often be complex wiring diagrams and lots of technical terminology. No doubt there are other industries where some technical background would help, too.

Also, many of the technical writing tools are quite complicated these days, and you will fare better if you have some technical skills in terms of web design (HTML and CSS).

What skills does a technical writer need?

As a starting point, I'd say you need these skills and qualities:

• Empathy. You need to be able to put yourself in the reader's position and understand how they feel and what problems they face
• Research skills. You'll need to research your audience and also the subject matter you are covering.
• Interview skills. You might not get to speak to users directly, but you will speak to developers and other stakeholders.
• Ability to write clearly and simply
• Ability to explain complex concepts in terms readers will understand. This often comes from understanding what they are already familiar with, and then drawing comparisons that they can relate to.
• Understanding of information architecture and how each piece of information fits into the entire documentation suite
• Ability to consider risks and other factors that may be missed by product developers. You don't just document how something works, you need to consider how it might be misused and the risks with that.
• Understanding of when to use images to help improve user understanding. Sometimes a diagram really makes the content easier to understand, especially with things like networks and installation instructions.
• Basic image editing for screenshots and diagrams.
• Basic screen recording knowledge for videos.
• Understanding of HTML (if working with digital outputs), basic CSS for styling it.
• Thick skin! Technical writing is often a thankless task, with too many people seeing it as a necessary evil rather than a valued part of the product.

All of those will help you create the right message for the end user.

But there are some other concepts and practices that you may need to understand too. These mostly relate to the features that are available in the common technical writing tools (more on those later).

If I was looking to hire a technical writer today, I'd be looking for some knowledge of:

• Topic-based writing.
  This is where you write each task or subject as a separate topic. Each topic usually has an introduction that explains the concept, instructions that explain how to perform a task, and a summary that explains what should happen and links to other tasks.
• Writing non-linear content.
  People don't read user guides from front to back in order. They dip in and out for the bits they need. So each topic needs to work as if it was the first page the user comes to (with links out to other relevant information).
• Content reuse.
  This is very important when writing content that needs to be duplicated in many different documents. Rather than copy the information, we write the information once, in one place, and reuse it wherever it is needed. Many of the leading technical writing tools have content reuse features and it is important to at least understand the concept of having "one source of truth" that is reused.
• Filtering.
  Filters are a common feature in technical writing tools, and they allow pieces of information to be included or excluded depending on different circumstances. I wouldn't expect someone to know how these work in every different product, but to have a general idea of how filters can be used in principle.
• Variables.
  These are also a common feature, and they let you tag terms in your content so that they can be swapped out when you publish. A common example is a product name. You have the product name as a variable so that if the product changes name later, you can make the change once in the documentation and it will update everywhere it is used.

Structured content, such as DITA or DocBook would be a necessity if the work involved using those, as there's quite a learning curve with those if you are coming fresh from writing Word docs. I wouldn't necessarily say you need to know the details, but to understand the basic concepts and have at least experimented in a demo version of whatever tool you are going to be working with.

‍

‍

What tools does a technical writer use?

This one can vary a lot, but you'll find that a lot of technical writers use specialist technical writing content management systems (CMS or CCMS) or Help Authoring Tools (HATs). Some commonly used ones are MadCap Flare, Paligo, and Heretto (formerly EasyDITA). Knowing how to use one of these will help you a lot, as they have some common features that are important to learn, such as topic-based writing and content reuse. It's also a good idea to get an idea of the way these products actually produce content.

I have not used EasyDITA, but can tell you that Flare and Paligo, while different, do have some similarities:

• You write the content in topics
• Style and content are separate. You write the content without worrying about fonts, colours, and all of that. You create raw content that can be formatted differently when used in different situations. The formatting or "styling" is done separately, either via settings in the product or via CSS. But this formatting is applied to the content at the publication level, not each individual topic.
• When you have created your topics, you create a publication and add the topics to it. This is like building a table of contents and choosing what topics you want to include.
• To create the finished documentation, you get the tool to publish it. Most can publish to different formats, so you could publish an HTML output and a PDF output from the same set of files.

These tools are expensive to buy, so if you are applying for a job that uses a specific tool, I'd try to get a demo and experiment with that. With subscription tools, I'd take the same approach and try to learn the basics from a demo.

But that's not to say that all jobs use these tools. In some places, you'll still find manuals being created in Microsoft Word. That's not great, really, as Word has its limitations and as you become more skilled in technical writing, you'll realise not having content reuse and other "advanced" features really hinders your progress.

What does a typical technical writing project look like?

It's difficult to say what a typical project looks like, as it can vary so much. Documenting a hardware project, such as a cooler, is going to be much different to writing API documentation. There are some common steps, though. For pretty much every technical writing project, you'll need to:

1. Research your audience. Who are they? What do they need? What do they already know? Customer-facing staff and customer support tickets are useful for this.
2. Consider your stakeholders. What are their priorities with the documentation? How do they want to deliver it?
3. Research the product or service. Meet the subject matter experts and get hands-on with the product to learn how it works.
4. Create the content, thinking carefully about structure, content reuse, user needs, safety, timescales etc.
5. Get the content reviewed for accuracy.
6. Edit the content based on feedback.
7. Get it reviewed again.
8. Publish the content when it is approved.

Of course, there are other things to factor in too, such as translation, managing multiple tasks and arranging meetings around those, handling last minute additions and features the devs forgot to mention and more. I've never seen a documentation team with enough staff, so it's normal to be constantly fighting against the tide of work.

‍

How do you get started as a technical writer?

I recommend taking a training course in technical communication and, if possible, getting access to demo versions of products like MadCap Flare to spend some time learning about the features and concepts. And don't forget to look in the documentation for these tools - you can find lots of great information about the tools, features, and technical writing best practices there.

In the past, I have recommended technical writing courses by Cherryleaf and Armada to people looking to break into technical writing. I am still in touch with a few of them and they have gone on to work as employed technical writers or contract technical writers. They all say how useful the training is, not only for the knowledge, but also for the confidence boost that comes with it. Also, I must mention Cake Content's bitesize learning courses which are a great and affordable way to learn about user-centred content.

My own route into technical communication was similar - I did a degree in technical communication and information design and was then able to go straight into work as a technical writer. Unfortunately, the degree courses seem to have died off in the UK, but there is a 2 year graduate course in Ireland.

Once you have some training under your belt, create a portfolio of explanatory pieces. For this, you could create documentation for household products or a service you are familiar with. If you don't have access to a proper technical writing tool, create the content in Word or Google Docs and add comments to show where you would have used filters, variables, content reuse and other advanced features. Being able to show you know how to use these features in context will help you land that first technical writing job or gig.

Could you break into technical writing without any training? Yes, absolutely. I have come across many people who have moved into it as a second career without training or experience. But I strongly recommend you take some training first. This is mainly due to the fact that there are a lot of untrained tech writers out there, churning out content and passing on bad habits. I've seen it in workplaces and in customer support, where people run into problems with their content because it wasn't planned properly at the start. Learn the basic principles and you can avoid problems that come further down the line when you have much more content to deal with.

‍

Communities and websites

I highly recommend the Write the Docs Slack community and Tom Johnson's I'd Rather Be Writing web site. Also, Cherryleaf have blog posts and a podcast.

If you are in the UK, check out the ISTC (Institute of Scientific and Technical Communicators). If you join, you can get access to their Communicator journal which has lots of interesting articles.

There is also the US-based STC (Society for Technical Communication).

When you're looking for work, Cherryleaf and 3di are a good starting point in the UK. If you decide to go freelance, get in touch as every now and again, I get jobs to pass on to others.

But don't just focus on technical writing! Look out for content design communities and UX writing communities too. The jobs are not the same, but there's still things we can all learn from each other.

‍

‍

‍