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.
- 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?
TURN STATIC DOCS INTO INSTANT ANSWERS
Build beautiful knowledge portals that are easy to navigate, search and share
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#
Frequently Asked Questions
Short answer: reliable functionality and fast time-to-value.
Your documentation should enable competent users to complete real tasks quickly, correctly, and safely in their own environment. Make functionality your north star and focus on:
- Clear outcomes: State the goal at the top so readers know exactly what they will achieve.
- Accuracy and testing: Specify prerequisites, environments, versions, and verified steps with expected results.
- Plain language: Use simple, consistent terms; define acronyms; avoid internal jargon.
- Context: Explain when to use the guide, who it’s for, and any dependencies or limits.
- Findability: Use descriptive titles, headings, summaries, keywords, and obvious navigation.
- Error handling: Include troubleshooting, rollback steps, common pitfalls, and safe defaults.
- Visual aids: Add screenshots, diagrams, or short clips where they reduce cognitive load.
- Safety and security notes: Call out destructive actions, required permissions, and data implications.
- Maintainability: Track versions, changelogs, owners, and review cadence; retire stale content.
- Success metrics: Monitor time-to-complete, error rates, search success, and related support tickets.
Litmus test: If a capable user can land on your page and finish the job on the first try with minimal friction, your documentation did its job.
Use 5W1H to make every doc purposeful and actionable by answering six core questions:
- What: Define the scope. Example: This guide covers setting up SSO with Okta.
- When: Clarify timing and conditions. Example: Use after creating an admin account.
- Where: Note where it lives or will be used. Example: Public knowledge base; mobile-friendly.
- Who: Identify the audience. Example: System admins with basic SAML knowledge.
- Why: Explain the benefit. Example: Reduce login friction and improve security.
- How: Provide steps to success. Example: Complete steps 1–6, then test and verify.
Paste-ready template:
Title: <What> Audience: <Who> When to use: <When> Why it matters: <Why> Location/Context: <Where> Prerequisites: <Required accounts, roles, versions> Steps (How): 1. <Step> 2. <Step> 3. <Verify result> Troubleshooting & next steps: <Known issues, rollbacks, links>Quick checklist: If each section is answered in one or two clear lines and the steps are tested end-to-end, your doc will be focused, relevant, and easy to act on.
Empathy helps you see the product the way users do, so you can prevent confusion, reduce cognitive load, and guide them to success faster.
Practical ways to apply empathy:
- Collect real inputs: Talk to users and support teams; mine tickets, search queries, and failure points.
- Use their language: Mirror terms users naturally use; define acronyms and internal names.
- Anticipate friction: Flag risky steps, call out edge cases, and add tips where people typically stumble.
- Design for cognition: Use clear headings, progressive disclosure (overview → steps → deep dives), and purposeful visuals.
- Be inclusive: Follow accessibility best practices (contrast, alt text, keyboard paths) and provide copy-paste examples.
- Offer paths for different needs: Quickstart for speed, deep dive for configuration, and troubleshooting for recovery.
- Validate and iterate: Watch a few users try the doc; note hesitations and fix those spots first.
- Close the loop: Add feedback prompts and keep an improvement backlog tied to real user pain.
You’ll know empathy is working when readers need fewer clarifications, complete tasks faster, and file fewer support tickets.
Treat it like a craft: practice deliberately, test with users, and iterate.
- Write regularly: Ship small how-tos, release notes, and task guides; volume builds skill.
- Adopt a style guide: Standardize voice, terminology, formatting, and examples.
- Apply 5W1H every time: Keep scope tight and outcomes explicit.
- Test your steps: Reproduce setups, validate commands, and note expected results.
- Collaborate with SMEs and support: Fact-check early and capture real-world edge cases.
- User test and revise: Observe one or two users; fix any blockers you see.
- Measure impact: Track time-to-complete, search success, and related ticket volume.
- Maintain a checklist: Headings, prerequisites, screenshots, warnings, verification, and troubleshooting.
A simple 30-day plan:
- Weeks 1–2: Draft and test two short guides; capture issues and questions.
- Week 3: Refactor using your style guide; add visuals and troubleshooting.
- Week 4: Measure outcomes, incorporate feedback, publish v2, and document learnings.
Then repeat with a slightly larger or more complex doc.
Archbee is a documentation and knowledge base platform for product, engineering, and support teams. It centralizes company knowledge and makes writing, collaborating, and publishing technical docs fast and reliable.
What teams use it for:
- Real-time collaboration and reviews with comments, mentions, and granular permissions.
- Content reuse via snippets, variables, and templates to keep docs consistent.
- Developer-friendly docs with API references, diagrams, and embeds.
- Versioning and change tracking so content stays accurate over time.
- Powerful search and navigation for better findability.
- Easy publishing to public or private portals with access control.
- Analytics to see what readers search for and where they get stuck.
Why it was created: When the whole team contributes in one place, knowledge stays current, onboarding accelerates, and users complete tasks with fewer escalations.
Archbee offers an unlimited free trial—sign up, explore, and try applying the 5W1H framework to your next doc.