How to write technical documentation

Start by considering yourself on a Sherlock Holmes mission to unlock the truth.

Ana
Ana
Storyteller. I balance information with feeling

đź“– Table of contents

Answer questions instantly

Build beautiful documentation portals that answer questions for your users, developers or team.

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?

Gif with sherlock holmes asking ''why?''

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.

Gif with sherlock holmes checking his watch

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.

4. 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.

After understanding the basic importance of these above 5W1H, one can easily use them according to his needs and make the documentation more authentic and interesting.

But what about when you can’t fully distinguish the motivations and needs of your reader?

Gif with sherlock holmes saying ''Know when you are  beaten.''

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.

Gif with sherlock holmes saying ''Really hard. Hardest thing i've ever had to do.''

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.

Gif with sherlock holmes being observative

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.

Gif with sherlock holmes saying ''Say that again''

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!

Gif with awesome transition with sherlock holmes

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

Frequently Asked Questions

What are the common misconceptions about technical professions?
Expand FAQ
Common misconceptions portray technical professions as solitary jobs, in which interactions and communications are not part of the job description.
What does the 5W1H rule stand for in technical writing?
Expand Button
The 5W1H rule refers to what, when, where, who, why, and how. These are the main questions a technical writer should ask in order to establish a relationship with the reader and deliver information effectively.
What to do when motivations and needs of the reader are not distinct?
Expand Button
When the motivations and needs of the reader are not completely clear, empathy is the go-to tool. Understanding and relating to the readers can significantly aid in creating an authentic and interesting documentation.
Why is data important in technical writing?
Expand Button
Data is crucial in technical writing as it helps to establish baselines and objectives. It provides useful information about the product and readers' experience and is key in optimizing technical documentation.
How can one improve in technical writing?
Expand Button
Improvement in technical writing comes from constant practice. Adopting a growth mindset, being open to collaboration and feedback, and improving social and empathy skills are also essential. It's important to write more in order to write better.

Read more in

Documentation