I see the messages and posts from workers wondering what technical writing involves and whether they’d be good at it. I get requests from my students at my alma mater asking for an informational interview about my career. Some feel that writing is easy, but some just aren’t sure if they can do it. Here’s the thing: if you’ve ever explained something complicated to someone and watched their face light up with understanding, you already have the most important skill. The rest is craft, and craft can be learned.
Here are ten principles to guide you as you begin.
1. Understanding unlocks capability
Your job isn’t to describe software, it’s to transform confused users into confident ones. Every paragraph you write should move someone closer to accomplishing something real. When you sit down to document a feature, ask yourself: “What will they be able to do after reading this that they couldn’t do before?” If you can’t answer that question clearly, you’re not ready to write yet.
2. Know your audience obsessively
Before you write a single word, understand who’s reading.
- What’s their job title?
- What pressure are they under?
- What does success look like in their world?
- What do they already know, and what will be completely foreign?
This isn’t optional background work—it’s the foundation everything else rests on. When you truly know your audience, the right words come easier.
3. The SME is not your audience
Subject matter experts live inside the product every day. They know the shortcuts, the edge cases, the history of why things work the way they do. Your users have none of that context. They’re coming in cold, trying to solve a problem and get back to their actual work. Write for them, not for the person who built the feature. If your SME says “everyone knows that,” question it. They’re often wrong.
4. Aim for clear, not clever
One clear sentence beats ten clever ones. If you have to reread something you wrote, your users will struggle twice as hard. Strip away jargon. Shorten sentences. Use words people actually say. This isn’t dumbing things down, it’s respecting your reader’s time and cognitive load. Clear writing is hard work, but it’s the work that matters most.
5. Structure is content
How you organize information matters as much as what you say. Users don’t read documentation like novels; they scan, they search, they jump around. A well-structured document lets them find exactly what they need in seconds. A poorly structured one buries information. Invest time in headings, hierarchy, and logical flow. Bad structure kills good writing.
6. Examples are not optional
Abstract explanations only go so far. Every concept should have a concrete, realistic example that your users can recognize from their own work. Show them the API call with real data. Walk through the workflow with a plausible scenario. Examples help them go through “I understand this in theory” towards “I can actually do this myself.”
7. Docs are a product
Treat documentation with the same rigor you’d apply to code: version control, peer review, user testing, and iteration. Documentation isn’t a one-time deliverable you hand off and forget. It’s a product that serves users every day. Hold it to high standards, measure its effectiveness, and improve it continuously.
8. Anticipate the questions they won’t ask
Great documentation answers the questions users didn’t know to ask.
- What assumptions are you making that they might not share?
- What prerequisite knowledge might they be missing?
- What will confuse them that seems obvious to you?
Thinking ahead saves users hours of frustration and prevents support tickets before they’re ever written.
9. Maintainability is part of quality
Documentation that becomes outdated is worse than no documentation at all because it can mislead people. Build processes to keep your docs current. Flag content that depends on frequently changes. Create review cycles tied to release schedules. Make updates easy instead of painful.
10. Listen to support and your users
Every support ticket is feedback on your documentation. Every question in a forum or chat is a gap you haven’t filled yet. Build relationships with support teams. Read the tickets. Talk to actual users when you can. Their struggles tell you exactly where your documentation needs work. Close those gaps, and you close the loop.
Here’s what I want you to take away: the measure of great technical documentation isn’t how much you’ve written. It’s how much capability you’ve unlocked for your users.
You already understand more than you think. You’ve explained things to coworkers, helped friends with technology, and figured out complicated systems on your own. Technical writing is that same instinct, refined and focused. Trust what you know, stay curious about what you don’t, and start there. Everything else follows.