Technical Writer Interview Questions

"I started in software support, answering tickets for a billing product. I noticed I was writing the same explanation again and again, so I started turning my best replies into help articles. My team lead saw the ticket count on those topics drop and asked me to own the knowledge base. That's when I realised what I actually enjoy: taking something confusing, figuring out what the reader is trying to get done, and making the path obvious. Since then I've moved into a proper writing role, covering an admin console and a small public API. What keeps me here is that good docs are quiet. Nobody thanks you, but fewer people get stuck. I'd like to go deeper on developer docs, which is why this role appeals to me."

"I do my best work when I'm treated as part of the product team rather than someone who gets a ticket at the end. That means seeing designs and plans early, having one named person I can ask about each feature, and reviewers who tell me plainly when something's wrong. In return I try to make myself easy to work with. I come with specific questions, I read the pull request before I ask, and I don't book a meeting when a chat message will do. I also give feedback on the product itself, like confusing labels or error messages, because I'm often the first person to use a feature like a customer would. At my last company, the team that worked this way shipped the best docs I've written, and the fastest."

"I'll use a setup guide I wrote for connecting our product to a customer's single sign-on. The readers were IT admins, who know identity systems well but didn't know our product. So I skipped explaining what single sign-on is and led with a short list of what they'd need before starting, because the most common failure was missing a certificate halfway through. I split the steps by identity provider instead of one long page with notes everywhere, and I put a troubleshooting section at the end built from real support tickets. Setup tickets on that topic went down noticeably after it shipped. What I'd change now is the screenshots. I used a lot of them and they went out of date within two releases, so today I'd keep only the ones that show something hard to describe in words."

"A senior engineer reviewing a troubleshooting page wanted me to add a full explanation of how the retry logic works at the top. I disagreed, because people land on that page when something is broken and they want the fix first. Instead of arguing in the comments, I suggested we keep the fixes at the top and move his explanation into a linked concept page. He wasn't sure readers would find it, so I added a one-line summary with a link right under the first fix. We also agreed to check the page feedback after a month. The feedback was positive, and a couple of readers commented they found the deeper page useful. What I took from it is that his instinct was right that the explanation mattered. It just belonged in a different place."

"I wouldn't start by writing a fifty-page guide nobody reads. I'd first collect examples of the inconsistencies that actually hurt readers, like the same feature called three different names, or different ways of writing steps. Then I'd suggest the team adopt an existing, well-known public style guide as the base and keep a short page of our own decisions on top, mostly product terms and a few formatting rules. I'd bring those decisions to the team as proposals, because writers follow rules they helped make. Then I'd make it easy: page templates for the common topic types, and where the tooling allows, a prose linter that flags banned terms in pull requests. Old pages I'd fix gradually, starting with the most visited ones, rather than a big rewrite project."

"My first pass would be: 'If you can't sign in, try again.' Here's what changed. 'In the event that' is just 'if'. 'It is recommended that the user should' says the advice twice and hides who's recommending it, so I turned it into a direct instruction to 'you', because the reader is the user. 'Authentication fails' is system language. The user just can't get in, so I'd use whatever word the screen uses, sign in or log in. 'Attempt to re-initiate the login process' is 'try again'. Then I'd push back on the sentence itself, because 'try again' doesn't help much. If I could find out why sign-in usually fails here, I'd write something like: 'If you can't sign in, check your email address and password and try again. If you've forgotten your password, reset it,' with a link to the reset page."

"I've worked in three kinds of setups. At my first job it was a company wiki, which was fast to edit but hard to keep consistent. Then a dedicated help authoring tool with reusable snippets and conditional text, which I used for a product with two editions. Most recently I've written in Markdown stored in Git, with a static site generator building the docs site, so I'm used to branches, pull requests and fixing a broken build myself. When I join a team with a new tool, I start by publishing one small real change end to end, from edit to live page, because that shows me the whole pipeline. Then I read the team's templates and a few recent pages. Honestly, the tool matters less than knowing the reader, but I don't want the tool to slow the team down."

"Docs as code means treating documentation the way engineers treat code. The content is in plain text like Markdown, stored in version control, often in the same repository as the product, changed through pull requests with reviews, and built and published automatically. The big benefit is that docs can change in the same pull request as the feature, so they're far less likely to fall behind. Engineers contribute more because it's their normal workflow, and you get automated checks for broken links, style and spelling. The trade-offs are real though. Writers new to Git have a learning curve, and reviewers outside engineering, like legal or support, can find pull requests awkward. And things a dedicated authoring tool gives you out of the box, like heavy content reuse, translation workflows or polished PDF output, are all possible but usually take extra tooling and someone to maintain it."

"I was documenting a new permissions model, and the one engineer who understood it was fixing production issues all week. My meeting requests kept getting declined. So I stopped asking for a meeting. I read the design doc and the pull requests, wrote a rough draft with my best guesses, and marked every line I wasn't sure about. Then I sent him five specific yes-or-no questions with the draft attached and said a reply in the chat was fine. He answered four in about ten minutes and corrected one assumption that would have been a real bug in the docs. For the last one he pointed me to a teammate. After that he started tagging me on pull requests himself, because he'd seen I wouldn't waste his time."

"First, I'd get the facts rather than guess from a demo. I'd message the engineer or product manager and ask what changed and whether it's final. Then I'd go through my pages and sort them into what's now wrong and what's only slightly out of date. Anything wrong in the setup steps or the release note gets fixed that day, because that's what users hit first. If something can't be finished in time, I'd rather remove or hide a section than publish wrong steps, and I'd tell support what's missing. After the release, I'd raise it in the retro without blaming anyone and suggest something small, like adding me as a reviewer on pull requests that touch the feature, so changes reach me automatically."

"The first thing I'd do is thank them, because a rewrite usually means my draft had something wrong, and that's valuable. Then I'd compare their version with mine line by line to see exactly which facts changed. I'd keep every correction but rewrite the wording for the reader, replacing internal names with the terms users see in the product, and splitting long sentences. Then I'd send it back and say something like, I kept all your fixes and put them into the language our users know, can you check I didn't lose any meaning? Most engineers are happy with that because what they care about is accuracy. For the future, I'd share our style guide and ask reviewers to leave comments on facts rather than rewriting text."

"I don't think lectures about the value of docs work. What works is being useful early and making docs part of the normal flow. So I ask to join planning and design reviews. Often my questions, like how would I explain this to a user, catch confusing product decisions before they're built, and that earns the team's respect quickly. Then I ask for docs to be part of the definition of done, so a feature isn't finished until the docs are reviewed. I make that cheap for engineers by preparing drafts and only asking them to check facts. And I share results in the team's language: this page cut these tickets, this error message we rewrote together stopped confusing users. Once people see docs saving them time, they start pulling you in."

"I once published an upgrade guide where one command had the wrong flag. It worked on a fresh install, which is how I tested it, but on an existing install it skipped a data migration. A support engineer flagged it after two customers hit errors. I corrected the page within the hour, added a clear note at the top saying what had changed, and worked with support so they could send the right steps to anyone affected. The real cause was that I only tested the happy path on a clean machine. Since then I test upgrade instructions on an environment that has old data, and for any command that changes data I ask the engineer who wrote the change to run through my steps before I publish."

"Support told me that questions about API rate limits were one of their most common ticket types. I looked at the tickets and saw the same confusion every time: people didn't know which limit applied to them or what the error meant. Our docs had one sentence on it, buried in a general page. I wrote a dedicated page with the limits per plan, the exact error response, and a short example of backing off and retrying. I also asked support to link it in their saved replies. Over the next couple of months, tickets tagged with rate limits dropped to roughly a third of what they had been. I'm careful not to claim it was all the docs, because support's saved replies helped too, but the page was the thing both fixes pointed at."

"I'd start by reading a handful of those tickets myself, looking for the exact error and anything the users have in common, like an operating system or an older version. Then I'd follow the guide on a clean machine that matches their setup, because I tested it on mine and my machine might already have something they don't. Most often the real problem is a missing prerequisite from an earlier step, or a step that does two things at once. The fix might be rewording, adding a check like run this command and you should see this output, or adding a troubleshooting note for the error. If the step is failing because the product behaves badly, I'd raise it as a bug too. Then I'd ask support to tell me if tickets on that step keep coming."

"I follow every procedure myself, exactly as written, not as I remember it. If I catch myself doing a step the page doesn't mention, that's a missing step. I try to do it on a clean setup, like a new test account or a fresh environment, because my machine usually has things already configured. If the steps differ by platform or permission level, I test the main variations, including as a user without admin rights, since that's where a lot of failures hide. For important guides I ask someone who hasn't used the feature to follow it while I watch without helping. And for code samples, I copy them from the page itself and run them, and where the team has the tooling, I like having samples tested automatically in the build."

"I'd look at a mix, because no single number tells you docs are good. On the site itself, search terms that return nothing are gold, since they show what people want and can't find. Page feedback, like a was this helpful vote with a comment box, points to specific problem pages. Then outcome signals: support tickets on topics the docs cover, and for developer docs, how long it takes a new user to make their first successful call. The limits matter though. High page views could mean a page is popular or that people keep coming back because it's confusing. A drop in tickets could come from a product fix. So I'd use numbers to find where to look, and then sit with users or read tickets to understand why."

"I was asked to document a message queue integration, and I'd never worked with queues. I had about two weeks. First I spent a day on the basics from general tutorials, just enough to understand producers, consumers and why messages get retried. Then I set up the integration myself in a test environment following the engineers' internal notes, and I wrote down every place I got stuck, because those were exactly the places a new user would get stuck too. By then I could ask the engineers precise questions instead of asking them to explain everything. I wrote the guide around the setup path I'd actually walked, and an engineer reviewed it for accuracy. The first thing she said was that my list of prerequisites was more complete than their own notes."

"A feature I was documenting moved its release forward by a week, which left me three days instead of ten. I listed everything I'd planned and asked one question of each item: will a user fail or open a ticket without this on day one? That left the setup steps, the one breaking change in configuration, and the release note. The conceptual overview, the advanced examples and updated screenshots went into a follow-up list. I told the product manager and support exactly what would be live and what would come the week after, so nobody was surprised. I shipped the essentials on time, and the rest two weeks later. The breaking change note mattered most, since it was the thing most likely to hurt existing customers."

"I'd write from whatever exists: the spec, the design mockups, the pull requests and any tickets. I'd ask an engineer for a fifteen-minute screen share where they run the feature while I take notes, or even a recording, which is often easier for them to give. I'd draft the pages with every unverified detail clearly marked, like exact button labels and error messages, because those change the most. Then I'd get the engineer to review the flagged items specifically. And I'd be open with the product manager that the docs are reviewed but not hands-on tested, and put a date in the calendar to walk through them myself as soon as the environment exists. I wouldn't let untested setup steps quietly become permanent."

"The test I use for every item is whether it changes what a user sees, can do, or has to do. If not, like an internal refactor, it stays out of customer release notes. I put anything that needs action at the top: breaking changes, deprecations and required upgrades, with exactly what to do and by when. Then new features, then improvements and fixes. Each item is written from the user's side, so instead of, refactored the export service, it's, exports of large reports now finish faster and no longer time out. I link to the full docs for anything bigger than a sentence. And I get the list from the actual merged changes and the product manager, not from memory, so nothing important slips through."

"At my last company the docs were organised by which team had written them, so a single setup task was split across three sections. I started with evidence: the most viewed pages, the site search terms, and the top support questions. It was clear people came in with tasks like set up, connect, and troubleshoot, not with team names. I drafted a structure around the user journey, with getting started, then how-to guides by goal, then reference. Before moving anything, I ran a quick card-sorting exercise with a few customers and support staff, which changed two section names. We migrated in stages, set up redirects for every old address so no links broke, and I posted a short note explaining where things had moved. If I did it again, I'd check the redirects with an automated link checker from day one."

"A task topic tells the reader how to do one specific thing, like create an API key. It's numbered steps, one action per step, with a clear result at the end. A concept topic explains what something is and why it matters, like what API keys are and how they differ from tokens. There are no steps in it. A reference topic is for looking things up, so it's tables or lists: every permission scope, every limit, every error code. People read them in different moments. When I'm doing a task, I want the steps and nothing else. When I'm deciding how to design something, I want the concept. Keeping them separate means each page is short and focused, and one concept page can link from many tasks instead of being repeated in each."

"I have a few rules I stick to. Before the steps, I list prerequisites, like permissions or software, so nobody fails halfway through. Each step is one action and starts with a verb, like select, enter or run. I say where before what, so it's, in the settings menu, select billing, because the reader needs to find the place first. If a step has a result they should notice, like a confirmation message or a command's output, I show it, so they know they're on track. Optional steps are clearly marked as optional, and warnings go before the step, not after. I use the exact labels from the interface in bold. And I end with how to check it worked, plus a link to the likely next task."

"I'd start by asking what's behind it, because there's usually a real goal, like new users not seeing the value and dropping off. Then I'd explain my concern simply. Someone on a getting-started page has already decided to try the product, and they want to reach a working result fast. Adding promotional language in between the steps slows them down and can make the docs feel less trustworthy. What I'd offer is a short opening line that states what they'll have working by the end, which is a benefit, just a concrete one. And I'd suggest the bigger value message goes on the product page or in a welcome email, where it belongs. If they're worried about drop-off, I'd propose we look at where people actually stop in the guide."

"I'd first check who's really reading it, using page analytics, search terms and the tickets support mentioned, because sometimes one side is louder than it is big. Usually both groups are right, they just want different things from the same subject. Experts want the command and the options. Beginners want to understand what's happening and follow steps. So rather than one page trying to do both, I'd split it: a short task page with the steps up front, a concept page explaining how it works, and a reference table for the options. At the top of the task page I'd put a one-line note for beginners pointing to the concept page. That way experts get a short page, beginners get the full story, and nothing is written twice."

"I try to answer four things before I write a line. Who is this person, meaning their role and what they already know? What are they trying to get done when they land on this page? Where are they coming from, like an error message, the product UI or a search? And what does success look like for them? I get this from evidence where I can: support tickets, search terms on the docs site, product managers, and whenever possible talking to a customer or a support engineer. Then I write a single sentence at the top of my draft, something like, a database admin who knows backups but is new to our tool wants to schedule a nightly backup. Every paragraph that doesn't serve that person gets cut or moved."

"At minimum it needs the method and path, one sentence on what the endpoint does, and what authentication or permission it requires. Then every parameter, whether it's in the path, the query or the body, with its type, whether it's required, default values and allowed ranges. Then a complete example request a developer can copy and run, and a realistic example response with every field explained, including which fields can be null. What's most often missing is the error side: which status codes this endpoint can return, what each one means here, and how to fix it. After that, things like pagination, rate limits and whether a call is safe to retry. Those gaps are exactly what turn into support tickets."

"Generation solves the structure: every endpoint, parameter and schema shows up and stays in sync with the code. But the reference is only as good as what's written in the spec. A description like 'the ID of the user' doesn't help anyone. So a big part of my job is in the spec itself, or in the code comments it's generated from: useful descriptions, realistic examples, what each enum value means, and every error response documented, not just the success case. I'd review spec changes in pull requests like any other code, and add a lint rule that fails when a field has no description. Then there's everything a generator can't write: the authentication guide, a quickstart, guides for workflows that chain several calls, and concepts like pagination or idempotency. Reference tells you what each call does. Developers still need to know which calls to make, and in what order."

"The goal of a quickstart is one thing: get the developer to a real, working result as fast as possible, so they believe the API works and it's worth their time. So I'd pick the simplest call that does something meaningful, not just a health check. The page would cover getting an API key, making that one call with a complete example they can copy in one or two common languages or a command-line request, and showing exactly what a successful response looks like. Anything optional, like configuration, other endpoints or best practices, goes into links at the end under next steps. I'd keep secrets out of the examples by using clearly fake values. Then I'd test it by watching someone who's never used the API follow it, and fix every place they hesitate."