Technical Writing Process

Technical Writing Process – How I Create Your Content.

For most documentation projects, I follow a simple technical writing process that I first learned at university and have developed over the years. This is how I go about making technical documentation that is interesting, easy to read, and carefully structured.

 

  1. Identify your Target Audience.
  2. Get the Right Tone of Voice.
  3. Plan Now, Save Time Later.
  4. Interview SMEs.
  5. Write Task-Based User-Friendly Content.
  6. Get Content Reviewed.
  7. Listen to your Customers.
Craig Wright

Craig Wright

Technical Writer

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 figure out who I am writing for. To do that, I need to create a customer profile, which are sometimes called a pen portrait. The customer profile is a simple breakdown of your typical customer, and covers things like their:

  • Age and gender
  • Education level
  • Job role
  • Level of experience in their industry
  • Level of experience with your product or services

With this information, I can determine how detailed the content needs to be, what type of vocabulary your customers will use, etc.

At this stage, I know who I am writing for. Next, I need to make sure I Get the Right ‘Voice’ for your Business.

2. Get the Right ‘Voice’ for your Business

People engage with writing that reads like a conversation with another human being. That’s why marketing professionals and copywriters use that style – they know it is easy to read and makes readers feel involved. Unfortunately, technical documentation has a reputation of being too minimalistic, stuffy and formal. But the times they are a-changing. These days, lots of companies recognise the importance of having a consistent ‘voice’ for communicating with customers, and so the gap between tech comms and marketing comms is narrowing. And about time too!

My approach is to pitch your content somewhere between the minimalism that keeps your costs down and the marketing ‘voice’ that’s easy to read. I like to think of it as a ‘journalistic’ style approach. It is focused on facts and remains concise, but it is written in a less formal style and maintains a flow that’s easy to read.

3. Plan Now, Save time Later

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 an 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 your content, and so will save you money in the long run.

But if you’re new to content reuse, or don’t have a good grasp of how the documentation project works as a whole, it is very easy to mess things up. I’ve seen projects where writers don’t use the snippets because they are so badly organised that they can’t find the content they need, and it’s not that uncommon to see snippets that are too specific to be reused. I’ve used snippets on large and small projects, so know what sort of problems can arise, and how to avoid them.

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, User-Friendly 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. Again, 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. The sign off is a requirement for my insurance policy, so has to be done before I can hand over content.

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 Started

Click the button below to get in touch.

Contact Straygoat
Share This