Today, let’s talk about technical documentation and what a good tech writer’s daily bread should be. As a tech writer, you have to bridge two worlds; the world of the client, who wants to write down everything to promote their own business and brand, and the world of the customer, who wants everything described in the simplest way possible. How can you deal with this approach? Where are the boundaries?
As a tech writer, I want to share some advice that can help you improve your writing so that when you ask a customer: "Have you read our guide?", you don't get the "TLDR" answer.
Understand the client's needs
The most important thing is to understand what the client actually wants. For some, the most important thing is the amount of documentation; for others, it is quality in small quantities. One client may target regular customers, another wants exponential growth of the number of new clients.
My advice:
- Meet the employees who are creating the product and find out their vision and goals
- Study any available feedback
- Use analytical tools that can tell you how users behave on your site, what they look for, how long they spend on each page, etc. All this information can help you understand your customers’ mindset
Put yourself in your customer’s shoes
Sometimes it can be very complicated, but try to think like a customer and go through your own guide step-by-step. You'll see that some things may not be as easy to understand as you might have thought. Pay attention to each word and stick to the same phrases and naming conventions the whole time.
Sometimes it's very helpful to ask a friend in the industry or an experienced consultant to see problems that might be eluding you.
Take your time in the testing part
If you're working on a more complex technical guide that describes setup step by step, consider adding a "test it out" section. That way, you can show how everything works and that you are able to do the setup and commissioning yourself. This can help customers a lot, especially if you show the testing on video, for example.
Simplify the language
Your guides can be read by customers all over the world. Keep this in mind when you're choosing complex phrases or long sentences. Idioms can “spice up” your text, jargon makes it more familiar, buzz-words more readable, but at the end of the day, in tech writing, the simpler the better. (Yes, I am using idioms in this article, but only because I can't use them normally.)
A picture is worth a thousand words
Lots of text, long sentences describing the problem in detail. Difficult to navigate when reading. Does this ring any bells to you?
Keep it simple and draw what you're describing. A diagram that describes flow can go a long way to help the user understand what they will achieve if they follow the guide. For example, a UML diagram is ideal.
Pictures have worked well for me, as well as short video tutorials with spoken word. And not just for me; according to a study by Mr. Adhan Kholis of the Department of English Language Education in Indonesia, students perform significantly better when videos or images are used in lessons. Ninety percent of the information we receive is visual, and the human brain processes images 60,000 times faster than text.
All of these elements will freshen up long texts and make the whole guide easier to understand.
A penny for your thoughts
Feedback is key. Take it constructively and make the best of it. A good example of who to get feedback from is:
- The person who gave you the assignment, be it a client or your supervisor
- An employee of the client who is not involved in the project but knows the company’s business
- Other tech writers
- Experts in the field/industry
- End customers
“Feedback is the breakfast of champions.” – Ken Blanchard
Use analytical tools
Feedback from people is very important, but it is not always reliable. Generally speaking, people don't like to give negative feedback. You can read more on this phenomenon in this article.
TIL: But why is it hard for people to give and receive negative feedback?
The most common answer is tied to our natural negativity bias. Prominent psychologists and neurobiologists have found that our brains are hardwired to react to negative stimuli faster, which was originally necessary for our survival. Sensing an attack would trigger our body’s natural fight or flight mode, increasing the amount of adrenaline released to the bloodstream, reducing reaction time and heightening our emotions.
So rely on hard data from analytical tools as well. It can show you how many users read your guide, how long they spend reading it, where they go next, etc. But, most importantly for a tech writer, it shows you feedback without the human factor.
Build a knowledge base and keep information up to date
Learn from mistakes and repetitive questions. By creating a knowledge base, you ensure that information is retained for internal use. This is particularly appreciated by people who provide technical support to customers. If you create a space for them to store their experience, you will save time and the clients’ money. A win-win situation for everyone.
You can't make an omelet without breaking eggs
Learning all these rules will take time for the client as well as for you. But it's better to be honest and spend more time getting a quality result than putting things together hastily.
Working on your project requires more than a simple copy paste. To build mutual trust with your client, find common ground and take inspiration from my advice.
You might also be interested in:
Let's talk about AI: #2 The Top 5 AI Tools for Technical Writers
Sources:
https://www.impraise.com/blog/overcoming-the-fear-of-feedback
https://deepstash.com/idea/22328/why-are-people-scared-of-feedback
https://www.eib.org/en/stories/learn-with-images
Author
Jan Řičica
Technical Analyst & Technical WriterHandles complete software analysis from taking requirements from clients to creating technical documentation.