When I left academia to become a technical writer in the software industry, I thought I had it all figured out. After all, I’d been a professor, a researcher, someone who could dive deep into complex ideas and explain them to a room full of students. I also had written in tech blogs for over a decade! How different could technical writing be?
Turns out, very different.
The learning curve hit me harder than I expected, and looking back, there are so many things I wish I’d known. If you’re just starting out, here are ten lessons I learned the hard way, sprinkled with stories from my own journey.
1. Know your audience better than they know themselves
When I first started, I assumed writing for developers was straightforward: just give them the facts, right? But what I missed was how varied audiences can be, even within the same group. Some developers wanted step-by-step tutorials, while others just needed a quick API reference. In Academia I was used to writing for experts and only experts. It is not uncommon to have to read a bunch of science articles before getting the gist of something. But this shouldn’t (almost never) be the case in technical writing.
Why it’s key: If you don’t deeply understand your audience, your docs will miss the mark. When you get it right, though, it feels like you’re speaking directly to their needs.
Personal takeaway: Early on, I wrote a guide assuming my audience understood certain technical terms. They didn’t. The feedback? “This doc is confusing.” Ouch. I’ve learned to ask, “Who’s reading this, and what do they really need?” Defining Developer Journeys (ot Critical User Journeys for my documentation) and using personas has been key.
2. Building trust with engineers is everything
I quickly realized technical writing isn’t a solo sport. Your job depends on building relationships, especially with engineers. They hold the knowledge you need, and earning their trust can make or break your work. And it is not only with stakeholders and engineering team.
But not only engineers. If you are lucky enough to work as part of a technical writing team, make the most out of it! I’ve learned more from a single peer review than from a bunch of articles like this.
Why it’s key: Engineers are busy, and they won’t prioritize docs unless they see you as part of the team. Building rapport makes collaboration smoother and more productive.
Personal takeaway: One of my first projects involved working with a developer who wasn’t exactly thrilled about explaining their code. I started by showing genuine curiosity about their work, asking thoughtful questions, and, even though I had no idea what I was doing, trying to contribute wherever I could. By the end, they were voluntarily sharing insights I hadn’t even thought to ask about. Being prepared and showing curiosity are key.
3. Don’t be afraid to ask questions
In the beginning, I hesitated to ask questions, worried it would make me look unprepared. But I learned that good technical writers are defined by their curiosity, not by knowing everything up front. This doesn’t mean you shouldn’t be prepared. It means that you should be ready to be the person asking the “dumb” question. Most of times, it is not as dumb as you think.
Why it’s key: Asking smart, specific questions shows you’re engaged and serious about getting things right. It also saves you from guessing and getting it wrong.
Personal takeaway: Early on, I’d spend hours trying to piece things together on my own. Then I realized that a five-minute conversation with an engineer could save me a ton of time and lead to a much better doc. Now, I treat questions like a superpower.
4. You’re not just a writer, you’re an advocate for clarity
I thought being a technical writer meant simply explaining what someone else built. But it’s so much more than that. You’re there to simplify complexity, anticipate user needs, and advocate for clarity.
Why it’s key: A good writer doesn’t just document systems, they improve them. In most cases, you should be the first real user of a new feature. Your fresh perspective can highlight gaps and improve the overall experience.
Personal takeaway: One time, I questioned why some actions could be taken several different ways in a product that I was documenting. That simple question led to a redesign that made the product more intuitive and saved users countless headaches.
5. Simplicity is a skill you develop
Here’s something I didn’t expect: writing clear, concise docs is incredibly hard. Simplicity takes effort, and it’s easy to over-explain or include unnecessary details.
Why it’s key: Your audience is busy. They need answers fast. If your doc is too wordy or complex, they’ll give up or worse, misunderstand. People usually read documentation trying to learn how to do something, and they want to leave and do the thing ASAP. Make it easier for them.
Personal takeaway: I’ve rewritten some docs ten times, cutting and refining until they were as simple as possible. The effort always pays off.
6. Tools are tools—skills are forever
When I started, I was hyper-focused on learning the latest tools, thinking they’d make or break my career. But tools come and go. Your ability to write clearly, organize information, and think like a user is what matters.
Why it’s key: Mastering tools is great, but your foundational skills (writing, structuring, and thinking critically) are what make you invaluable.
Personal takeaway: I once spent days obsessing over a new docs-as-code tool, only to realize I could’ve delivered the same quality using different templates in my current tool. Lesson learned.
7. You’ll need to champion documentation
Not everyone values documentation as much as you do. Part of the job is showing stakeholders why docs matter and how they make a tangible impact.
Why it’s key: Without advocacy, documentation often gets deprioritized. Showing its value ensures it gets the attention it deserves.
Personal takeaway: I started tracking metrics like reduced support tickets and faster onboarding times. When I shared those numbers with the team, their attitude toward documentation shifted completely. Especially for leadership, numbers speak louder than words. And that is even more true when those numbers have dollar signs attached to them. That is: show that your work reduces costs.
8. Deadlines are sacred (even if they’re flexible)
In academia, deadlines often felt more like suggestions. I’ve seen people extend their scholarships and grants for years. In the software industry, they’re non-negotiable. Docs need to be ready when features ship, and your ability to meet those deadlines builds trust.
Why it’s key: Delivering on time isn’t just professional, it’s crucial for the product’s success.
Personal takeaway: I’ve learned to prioritize ruthlessly, focusing on the highest-impact tasks first and leaving the “nice-to-haves” for later. Perfect is the enemy of done.
9. Curiosity will keep you growing
The best technical writers are always learning. Whether it’s a new technology, a different writing style, or a fresh way to structure information. Curiosity is what keeps you adaptable.
Why it’s key: The tech world evolves fast. Staying curious ensures you evolve with it.
Personal takeaway: I think I had a lead start with this one. By the time I became a tech writer (in my thirties) I already knew how I learned best and I kept myself curious because, as a researcher, that is the only way of doing things. So learn how you learn and learn how to like it.
10. Confidence takes time, but it’s worth the wait
When I started, I felt like an impostor. I was constantly second-guessing myself. But over time, I realized that my unique perspective and skills added real value. I’m still far from where I want to be, but I feel confident about what I know, what I can do, and how to make it.
Why it’s key: Confidence allows you to contribute fully and advocate for the user experience with authority.
Personal takeaway: The first time a stakeholder told me my documentation had made their job easier, I finally felt like I belonged.
Wrapping it up
If I could go back and give myself one piece of advice, it’d be this: embrace the learning curve. Every mistake (and every time someone corrects you) is a lesson. Every challenge is an opportunity to grow. And every document you write is a chance to make someone’s life a little easier.
There’s a bunch of other tips that had helped me grow, but these were the first obstacles I had to sort. What about you? What do you wish you’d known when you started? Let’s share the lessons and keep learning together.
Leave a Reply