How to write technical documentation

Storyteller. I balance information with feeling

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

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.


Frequently Asked Questions

What is the main focus in the technical community?
Expand FAQ
In the technical community, the main focus is on functionality.
What is the 5W1H rule in technical writing?
Expand Button
The 5W1H rule in technical writing stands for what, when, where, who, why and how. This approach helps in understanding the reader and his/her context better, to create a connection and to make the content more relevant.
What is the role of empathy in technical writing?
Expand Button
Empathy can be used when writers can't fully distinguish the motivations and needs of their readers. It is about understanding and connecting with readers, taking interest in their issues, developing listening skills, and noticing nonverbal cues. Empathy improves the process of collecting data and it helps in making documentation more authentic and interesting.
How can someone improve their technical writing skills?
Expand Button
Improving technical writing skills requires practice, a growth mindset, and an openness to feedback. Collaboration, keeping an open mind to suggestions, writing more and more often can help a person improve his/her technical writing skills.
What is Archbee and why was it created?
Expand Button
Archbee is a tool created to improve the process of writing documentation. It centralizes a company's information which makes the writing and collaboration process more efficient. It was set in motion based on firsthand experience of the difference it makes when the whole team is involved in the process of writing documentation.

📖 Table of contents

Answer questions instantly

Create and share documentation that answers questions instantly with Gen AI

Discover Archbee

Receive documentation and technical writing tips & trends — our newsletter

Join 5000+ people from around the world that receive a monthly edition of the Archbee Blog Newsletter.