(mis)adventures of a technical writer

  • I work at Google, but I don’t use Google Search

    It always surprises people when I tell them I use DuckDuckGo instead of Google Search. They assume I’m making a privacy statement. I’m not. It’s about control. And I want to note that this post is not an ad for DuckDuckGo (although after reading it whole, it seems like it), it just happens to be the search engine that better suits my needs.… (read the rest)

  • When to use notes, warnings, and callouts in tech writing (and when not to)

    I think it was Fabrizio Ferri Benedetti who made a list about topics he would like to see writers write about. Or maybe I saw it in a discussion in the Write the Docs Slack. Regardless of that, I think this subject is worth a post.

    To be honest, I just wanted to acknowledge this was not my original idea. But, in this day and time, what is an original idea?… (read the rest)

  • Why writing small docs is a game changer

    In software development, there has been multiple instances of people advocating or discussing opting for small commits. This makes sense for a number of reasons, but there are also writers in my company advocating for small docs. And it makes sense.

    As technical writers, we aim to make information clear, accessible, and actionable. But there’s another factor to consider: how the size of a document impacts its effectiveness.

    (read the rest)
  • 10 things I learned the hard way about technical writing in tech

    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?… (read the rest)

  • How to interview a technical writer: Lessons, tips, and questions

    Hiring a technical writer isn’t just about finding someone who can write well. You need someone who can navigate technical complexity, collaborate with engineers, and bring clarity to the chaos of development processes. It’s about finding a curious, resourceful problem-solver who thrives in ambiguity.

    Over my career, I’ve conducted more than 70 interviews for technical writing roles. My very first interview?

    (read the rest)
  • How to ask questions to SMEs as a technical writer

    If there’s one thing I’ve learned as a technical writer, it’s that asking good questions can make or break your documentation. Subject matter experts (SMEs) are often your gateway to understanding the intricacies of a product, feature, or system. But let’s be honest—getting information from SMEs isn’t always straightforward.

    They’re busy, they might not know how to explain things to non-experts, or sometimes they just forget we’re not telepathic.… (read the rest)

  • Beyond coding: Project management is the best ability a tech Writer can have

    /Like it or not, a project management mindset can get you to your next level in your technical writing career.

    When people think about technical writing, they often imagine someone immersed in markdown files, fiddling with APIs, and even dabbling in a bit of code. (Or maybe that’s how I want people to think about me.)

    And while those skills are helpful, there is one under-mentioned superpower of a technical writer that almost no one talks about: project management.… (read the rest)

  • My talk about Minimum Viable Documentation

    I’m giving a talk on the upcoming DevFest Munich 2023, organized by the Google Developers Group in Munich. It’s a 1-day tech that will offer tech talks, workshops, and opportunities to meet people in the industry.

    In my case, I wanted to talk about documentation in a relatable way. That’s why my talk is called Just document it: Minimum Viable Documentation.… (read the rest)

  • Using personas in technical writing

    Technical writers often face the challenge of creating complex technical content that is both accurate and engaging. Using personas can help technical writers overcome this challenge by providing a clear target audience.

    In user experience (UX) design, personas are fictional characters representing the different types of users who might use a product or service. These personas are based on user research and are designed to help designers and other stakeholders understand the needs, goals, and behaviors of the different types of users.… (read the rest)

  • Writing great release notes

    Release notes are the way we let users know about changes in our application or service. 

    Unfortunately, users and developers often ignore them, and tech writers consider them one of the most boring types of technical documentation. So, obviously, I wanted to talk about them.

    Something to get out of the way before starting is the usage of the term. We use release notes when you have different versions of a software or application.(read the rest)