How to write technical documentation

When you think of IT and technical cult series, Big Bang Theory and The IT Crowd are probably the first to come to mind. Maybe Mr. Robot, to tap into the niche of the more dark-to-noir genre. If we further consider the characters and situations, what they tell us is that technical professions are regarded as solitary jobs, for which interactions as well as communication aren’t part of the job description.

Even for technical writers, the criteria in assessing work performance has more to do with putting together and explaining information, and less with style and fluency, the all-time writer’s tools of the trade. Inside the technical community, the main focus is functionality, and the mission of technical documentation is to get you through the user journey, from point A to point B. Right?

That’s half true, half a misconception. Why, you’re asking yourself?

Elementary, my dear Watson.

Functionality is important but questions are the key in delivering information.

The 5W1H rule: what, when, where, who, why and how#

Functionality is indeed the number 1 asset of technical texts. But to maximize it, you also need to establish a relationship with your reader. Which in return, takes knowing a thing or two about him. Not what’s his name or how he takes his coffee, but the more general whats & hows. The explanations behind his willingness to spend precious time to read exactly your piece of info.

The main core of understanding the reader is based upon asking yourself the following questions: what, when, where, who, why and how is he going to access and use the material. The rule can be successfully used in any form of communication, as it creates the premise for a connection. If when going through the text, the reader will say: that’s exactly why I’m here, this is written for me, then you asked and answered correctly.

I want to be very clear about how this works.

Let’s add some more details to every question, to better understand the importance and correct use of each of them, as follows:

1. What: As the name itself explains its meaning, you need to properly establish from the beginning the scope of the text. Then write it down in a simple, easy to understand way, so there’s no room for ambiguity.

2. When: When refers to the moment in which the given text will be useful, including context, conditions to be met and any relevant clarifications.

3. Where: It includes the channel used for the distribution of the material. Is it private, public? Is it print, or digital? Each of these corresponds to a specific approach towards the reader.

1. Who: This is the main part of 5W1H rule, as audiences differ greatly according to age, background, interests, culture, zodiac sign, weather conditions. Well, not all of these criteria are necessarily objective and relevant, but most are. And of course, you must know how explanations given to a kid vs to a parent differ. No words or reasons are universal. They work better or worse, depending on your crowd of choice.

5. Why: This is also a crucial element as it binds together your own motivation and interest in the text with your reader’s. The why guides you both through the documentation, eye to eye on the desired outcome.

How: At last, keep in mind your reader is lazy and it expects you to feed him all the steps necessary in order to accomplish his goal. This is where the how comes into focus.

Once you understand the basic importance of the 5W1H mentioned above, you can easily use them according to your needs and make the documentation more authentic and interesting.

But what should you do when you can't clearly identify your reader's motivations and needs?

There is still hope to pull it off remarkably.

Let me tell you my go-to answer.

Where questions fail, make room for empathy#

You feel enlightened and in-tune with your users. But it’s not quite enough. Your doc is still incomplete, but you know it can be better. The only challenge is that you have a lot of questions. Now what?

Let yourself be human.

Not even your best dev will write an algorithm to automate docu-writing.

At its heart, technical writing is a people game. It’s not a job for a computer.

But you need data. If you want to know where you’re going, you need to `compute` relevant facts and figures. Data helps you establish baselines and set objectives.

I guarantee you that piles of useful information about your product and your users’ experience wait to be discovered elsewhere in your organization: in a salesperson’s head, in contact reports maintained by your technical team, or in the troubleshooters’ ticket management system.

The more energy you put to working with real people, for example colleagues or kith, the better you will get at collecting data. So get out there! And since direct interaction is fueled by empathy and social skills, there’s where you might want to get started working on.

Start in small ways. Start developing your social persona by engaging with people you interact with on a daily basis. Have genuine interest. Develop your listening skills. Take notice of nonverbal communication, body language (such as smiling and nodding) and the vocabulary they use to get a conversation going. Pay attention.

If you’re not used to this, go the extra mile to really let the behavior sink in.

Practice makes perfect#

What I know about empathy is that it’s just a skill, like any other else. Acquiring new skills can be intimidating and scary when you’re just starting out, but don’t let that stop you from working at getting better. Adopting a growth mindset and recognizing that you are capable of building empathy is essential.

The same applies when it comes to writing in general and technical writing in particular.

You have to write more, to write better.

There’s no easy way out or miraculous steps that will turn your documentation into an easy-to-read, pertinent material overnight. But as soon as you see the miraculous advantages of collaboration, keeping an open mind to what others have to say, your perspective will transform from the roots.

And who knows what else this journey will bring you.

For us, this is how Archbee was set in motion. By seeing firsthand how much of a difference makes in writing documentation when the whole team is onboard. We wanted to create a solution to simplify that so we asked ourselves, how would the process look with only one place to centralize a company's information?

And here’s where it led us. Quite the ride!

Thus you are not alone on this path. We are right next to you and so are our 500+ clients who discovered the advantages of working smarter and more efficient on documentation. But don’t take our word for granted. Ask your own questions and test your own tools.

Hope we answered your question about how to write technical documentation!

Archbee has an unlimited free trial, ideal for trying out the software and seeing how it works. Give it a chance yourself: sign up, get comfortable and pour in some of the 5Ws.

FAQ#