One of my favorite things about being a technical writer in the software industry is how interdisciplinary the role can be. The intersections with engineering are obvious, but for me, the most interesting cross-pollination occurs where my work overlaps with that of UX and product design: crafting the user journey through the documentation that I write and maintain. It’s one thing to write the docs; it’s another thing entirely to understand (and speak to) the various paths that different types of users will take through those docs to try to find what they need.
As a writer, what I find most exciting about this is that it’s essentially a form of storytelling: you’re constructing a narrative and then expressing it through both the written materials themselves and the order in which you present them to the user—one facet of the overall information architecture. To pull this off well requires a great deal of empathy, creativity, and imagination—muscles we don’t get to flex too often when documenting APIs and SDKs. It also requires you to have a deep understanding of both the user’s and the organization’s needs.
With such an open-ended challenge, how do you decide what story to tell? When the product exists to serve many different use cases, which paths do you prioritize through the docs and why? When the needs of the organization don’t neatly align with the needs of the median user, who do you aim to serve first and foremost?
Understanding the user’s needs
To craft a compelling story that resonates with your users, you have to deeply understand their needs. For software documentation it certainly helps if you have experience in the niche you’re writing for, but I wouldn’t say it’s a hard requirement. Highly skilled product engineers sometimes struggle to empathize with less experienced users of their products because they expect their audience’s expertise to match their own, which is not always the case. A talented technical writer knows how to speak to users across a wide range of skill levels, and can tailor documentation to meet users where they’re at.
To understand user needs at this stage in the process, I gather data to try to answer the following questions:
- Where are users coming from when they land in the docs? (Google, company blog, etc.)
- What is their typical role and skill level?
- What kind of organization do they work for? (Enterprise, startup)
- What kinds of actions do they take when they show up?
- How long do they stick around? (bounce rate)
- If they’re looking for specific information, what do they do to find it?
- Do they use the site’s built-in tools for searching (if applicable) or are they more inclined to use Google?
- If they have a use case in mind, what is their experience like when they attempt to implement it using our docs?
- Is there any specific terminology they expect to see when reading docs like these?
Some of my favorite techniques and exercises for answering these questions include:
User surveys
You can simply ask your users what they need. Groundbreaking stuff, I know. Trouble is, users don’t always know what they need; or they don’t know how to describe what they need; or they just aren’t interested in filling out a survey for you (fair enough). The challenge lies in having a large enough pool to sample from, and then asking questions that are specific enough without accidentally biasing a particular response, and open-ended enough without requiring too much cognitive effort to answer.
It helps if you’ve formulated specific hypotheses about the kinds of experiences users are having with your docs—then you can write questions to test out your assumptions and vet alternative perspectives. If you plan to conduct surveys on a routine basis (like once or twice a year), it’s a good idea to come up with a couple simple questions about satisfaction and ease of use (“rate on a scale of 1-5”) that you can repeat in every survey and measure over time.
User interviews
When Paul Graham talks about the value of “doing things that don’t scale,” I immediately think of user interviews as the quintessential example for technical writers. They’re time- and energy-intensive, but so incredibly valuable when you get them right. When you have actual conversations with the users of the software you’re documenting, you don’t just learn about the problems they face, but crucially, you learn how they describe those problems. You can then repeat those descriptions in your documentation to speak to the rest of your users with the kinds of phrases and terminology that they’re expecting—or better yet, anticipate their needs before they’ve even fully formulated them. (That’s one way to turn a casual user into a super-fan.)
Internal surveys and interviews
The engineers who build and maintain the product are often solid candidates for consumers of that product, so they can serve as excellent stand-ins for your users if/when you’re not able to get adequate feedback from your user base. One key difference is that you can generally ask more of your colleagues than you can of random strangers who use your product, so you might be able to delve deeper into their experiences with the docs and extract more honest responses. All the better if you can get buy-in from senior stakeholders in engineering who recognize the value of this and encourage their direct reports to participate.
User personas
Once you’ve gathered a fair amount of data from surveys and interviews, you can aggregate it to compare and contrast experiences and look for commonalities that point to specific use cases that your product addresses. Ideally, you should be able to distill these experiences into one or two personas—the “archetypes” who represent the majority of your users and exemplify their needs. The possibilities for such an exercise are endless, but I like to keep it fairly simple by writing a paragraph or two about each persona, giving them a real human name and a typical background in their industry, and describing the problem they’re trying solve.
Something like: “Tom is a DevOps engineer with 8 years of experience. He’s knowledgeable about cloud computing in an enterprise setting but less experienced with newer automation tools. His manager has asked him to evaluate Automation Product X to see if it will meet their team’s needs, including frictionless onboarding, support for Y and Z services, and a smooth integration with A and B platforms.”
These kinds of details are precisely what we technical writers need to effectively map out the journey that we want users to take through the docs we write. With an example like the one above, I have a strong sense of the typical user’s skill level, their familiarity with the product niche, and the main points I need to address through both copy and technical content to meet their expectations. The story I should tell follows naturally: Automation Product X is simple to install and supports Y and Z services with minimal configuration. Here are tutorials for integrating Product X with Platform A and Platform B. Couple that with API and/or SDK references and you’ve got a very solid v1 documentation product.
Understanding the organization’s needs
Of course, when it comes to an actual organization that must generate revenue and support a sustainable business model, the user’s needs don’t tell the full story. The approach I’ve outlined works well when writing for your existing users, but what do you do when the organization expands the product offering into novel territory? The business may be trying to address needs that the existing users don’t even know they have yet, or to reach entirely new kinds of users who come from different backgrounds and have new kinds of problems to solve.
This is where it becomes crucial for the technical writer to have a seat at the table with colleagues in marketing, developer relations, and product design. A skilled technical writer knows how to draw from these related disciplines to craft a narrative that reflects the market research, the community pulse, and the value proposition of the solution. And when that writer is armed with a deep understanding of the product and its existing users, they should be able to help shape the conversations that take place across functions about what problems the product aims to solve—and how to effectively describe both the problem space and the product.
Taking a use case-based approach
Regardless of what the research tells me about existing or potential users, I always aim to take a use case-based approach to the user journey. What I mean by that is, when a user lands on the “front page” of the docs, they should be presented with one or a few of the possible paths they could take through the docs to implement the most common use cases for the product. When the docs are disjointed or not logically connected through the site’s IA, the user will struggle to understand what actions are available to them and where they should go next. Mapping out the user journey, then, is really about making the docs site tangible to the reader: they need to know what all of their options are, and ideally, which one to pick first.
User personas are really helpful throughout this process as well: a skilled technical writer knows how to roleplay as the persona they’ve created, experiencing the documentation through the eyes of the archetypal user they’re trying to optimize for. I like to think of this as inhabiting the “beginner’s mind,” which is a crucial skill for technical writers to cultivate. The Zen master Shunryu Suzuki says that “in the beginner’s mind there are many possibilities, but in the expert’s there are few.” In this context, I take that to mean that new users don’t know what they don’t know—they’re operating in the realm of “unknown unknowns.” One of the most important parts to nail in the user journey is to get them from that state to the state of “known unknowns” as quickly as possible, to pare the limitless possibilities to the few specific implementations available to them.
Deeply human work
Here in late 2025, I would be remiss if I didn’t acknowledge the existence of large language models and their potential to reshape how we technical writers operate. Fears continue to mount as many worry that LLMs will usurp their roles, and for better or worse, this sea change is already under way: LLMs can do a pretty decent job “writing” reference materials, given enough training data.
What they can’t do (yet, and maybe not ever) is effectively strategize about what to write and how to present it. They are incapable of empathizing with the users their docs are intended to serve. Crucially, they can never innovate novel solutions—only regurgitate what’s already been done elsewhere. They cannot replace the expertise of a writer who understands the big picture of delivering documentation as a product unto itself. LLMs certainly can augment the process of mapping out a user journey (for example, by helping to formulate survey questions or fleshing out personas), but it takes human ingenuity and creativity to carry out the big-picture, long-term strategy that results from those exercises. And that’s where the real magic happens.