Technical writing process

How I make sure your content is pitched at the right level

Technical writing process

How I make sure your content is pitched at the right level

How I create your technical content

If you’re new to working with technical authors, you may be unsure of what to expect when you hire me. So here I’m going to give you a quick overview of the typical process for creating your documentation. 

There is a section for each point in the list, so hit the links for details.

  1. Identify your target audience.
  2. Get the right tone of voice.
  3. Plan what to write and what to reuse.
  4. Interview SMEs.
  5. Write task-based content.
  6. Get content reviewed.
  7. Listen to your customers.

This process is common to most types of content creation, and you’ll see a similar approach from content designers. Note that I’ve not included any information about the project management side of things, as that can vary depending on your own working practices. For example, I’ve worked for several software teams that implement agile differently.

Even if we don’t end up working together, I hope there’s some ideas in my technical writing process that you can use. Because you never know, maybe one day I might be one of your customers and just like everyone else, I don’t want to read dreary, confusing documentation!

1. Identify your target audience

The first step is to identify who I am writing for. To figure this out, I will ask you about your customers, in particular their age, gender, education level, job role, experience in your industry, and knowledge of your products.

Ideally, I will also be able to speak to your customer-facing staff, such as your support team and sales team. These people have direct contact with your audience, so can provide me with valuable details. 

2. Get the right ‘voice’ for your business

With copywriting, there are many different tones of voice, and it is my job to make sure the language fits the nature of your business. But with technical writing, it is different – the focus is on presenting information as clearly as possible, especially if the audience may not have English as a first language or your content is going to be translated. 

For technical communication, I aim for a journalistic style that is easy to read (like marketing) but is clear and concise (like traditional tech comm). This gives a good balance between marketing comms and tech comms, makes sure your content is easy to understand, and helps to keep localisation costs down. 

3. Plan what to write and what to reuse

By this stage, I have a good idea of who I’m writing for and what sort of language to use. So now I can start planning the content. There are two parts to this – planning the scope and planning for content reuse.

Planning the Scope

This is where I figure out what needs to be covered and which topics are priorities. I can usually get this information from the brief, from the list of documentation requests or tickets, or from a quick chat with a subject matter expert (SME).

Planning for Content Reuse

Modern technical writing tools such as MadCap Flare and Paligo have content reuse features that allow me to use the same ‘snippet’ of text in lots of different topics. This can really reduce the amount of time it takes to update and manage your content, and so will save you money in the long run.

But to use these features effectively, there needs to be a clear strategy in place. The ‘snippets’ need to be used and organised consistently. Otherwise, your project can turn into an overcomplicated mess that becomes difficult to manage. 

You can learn more about content reuse and how it can save time and money in my blog post  – Content Reuse.

4. Interview your subject matter experts

Okay, now we’re getting into the content. On most projects, I begin by reading up on whatever information already exists, such as design briefs and marketing material. Sometimes, I can get all the information I need from that, but it is more likely that I’ll need to ask your SMEs for more information or a demo. At the time of writing a topic, I need to completely understand how a feature works.

But don’t worry, I’m also very mindful of disrupting your SMEs, so always make sure I’m well prepared so that I can get the information I need as quickly as possible. Sometimes, additional questions crop up as I’m writing, but these are few and far between.

I’m also used to working with techies! I’ve worked in software development teams for most of my career, and have dealt with a wide range of personality types and can build up a good rapport.

5. Write task-based content

Great content is at the heart of a first-class customer experience. Although I don’t follow a set structure when writing content, for most topics, I use this sort of approach:

  1. A ‘hook’ introduction. I hate seeing ‘In this topic you will learn about…’ as a start. How boring. I’ll make sure your introductions are interesting and focus on benefits.
  2. Conceptual information. ‘How to’ is rarely enough. For better understanding, your customers need to know how a feature fits into the bigger picture and when and why it should be used.
  3. Instructions. I provide instructions that are in a logical order, using numbered steps and tables where appropriate. The important thing here is to make sure the sequence is accurate.
  4. Example. An example can help readers understand how a feature works in the ‘real world’. I try to write examples that show a common use of a feature.
  5. References. It’s important to include links to other topics that contain related information. With some products, this can be achieved with taxonomies, categories, or concept links.

This process helps when structuring topics, but to make the content really connect, it still boils down to writing skills. That’s where you benefit from my training and years of experience – I know how to judge whether there’s enough or too little information, and will make sure your content reads well, flows, and uses appropriate language.

6. Get Content Reviewed

Once I’ve created the content, I get it reviewed by your SMEs and if possible, other writers. I’m looking to SMEs to spot technical errors or bits of information that are missing (sometimes they can forget to mention something in demos). When writers review the work, they tend to focus on the content and pick up on style issues. I then fix any issues and, if needed, put the content in for another round of reviews. This is a really effective way of quality control, but it does depend on the availability of others. As before, I’m also aware of your SMEs’ workloads, so try to stagger the reviews in small amounts, so that they aren’t overburdened (and also so that they don’t rush through it).

When the content is ready, the next step is to get it signed off and published. 

7. Listen to your Customers

The best way to make sure your content is working for your customers is to listen to what they have to say. Asking customers to provide feedback on topics and in manuals is quite common, and its also possible to monitor which topics customers visit by using analytics.

Let's get your content project started. Get in touch and let me know what you need.

craigwright@straygoat.co.uk

+44 07954141761

Contact Craig
Share This