Technical Writing – My Approach
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.
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.
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.
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.
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:
- 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.
- 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.
- 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.
- 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.
- 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.
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.
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.