Technical Writing – My Approach

Software technical writer - Craig Wright

Craig Wright

Experienced software technical writer based in Chesterfield, Derbyshire, UK.

Your documentation is an important part of the overall customer experience. Get it right, and your customers will be able to find the information they need with ease. They'll appreciate that you've thought about their needs and provided content that makes their lives easier. It also helps your customers to become better at using your products and enthusiastic about your brand. That's important in these days of social media, as your loyal customers can be influential advocates and help your business grow (for free).

But how do you make sure your content is engaging?

I can't speak for all technical writers, but what I will do is share the basics of my working process with you. This will show you 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.

Even if we don't end up working together, I hope there's some ideas here that you can introduce in your business. 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 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. I create a customer profile for each level of end user, so that when I write a topic aimed at them, I can imagine it as a one-to-one conversation.

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 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!

You'll be glad to hear that I've trained and worked as both a technical writer and a copywriter. So I understand the key principles and techniques of both styles of writing and can use both to make sure your content is easy to read and interesting. I generally adopt a conversational style as that's what connects with readers best. But that style needs to be used with care. There are different levels of 'chatty' and it takes a bit of skill to get the balance just right. Don't worry, I know how to turn that 'chatty' dial up or down as needed.

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.

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. They didn't teach this aspect of the job at university, and when I was first starting out, it was one of the biggest challenges of the job. I need SMEs to feed me information, so it's really important that I can build up a good rapport.

I've learned that humility, politeness, and taking a little bit of interest in SMEs as human beings rather than just fountains of knowledge helps everyone to work better as a team.

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.
An example topic from a MadCap Flare project
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. I'll be honest with you, most clients neglect this step, but that's their loss. Listening to your customers is a sure-fire way to identify weaknesses and improve your content. I can help implement these feedback requests in your project, so that your customers are encouraged to get in touch.

Technical Writing Feedback