How do you approach writing documentation for a feature you don't fully understand yet?

I start by using the product myself if it's available, because clicking through something teaches me more in ten minutes than reading a spec does. I make a list of every question I can't answer from using it: edge cases, error states, what happens if I do something in the wrong order. Then I take that list to the engineer or product manager who built it, rather than asking them to explain the whole feature from scratch, because a specific question gets a specific, useful answer and respects their time. I also read any existing tickets, design docs, or Slack threads about the feature, since a lot of the reasoning behind a decision lives there rather than in the final spec. Once I have a working model of the feature, I write a rough outline and share it early, before I've invested time in full prose, so any misunderstanding gets caught while it's cheap to fix. I did this recently for a permissions system with several inherited roles: I built a small table mapping role to access level before writing a single sentence of the actual guide, because I needed to understand the logic myself before I could explain it to anyone else.

What does your documentation review and editing process look like?

I edit in stages rather than trying to catch everything in one pass. The first pass is structural: does the document answer the question the reader came with, and is the information in the order they'd need it, not necessarily the order it was explained to me. I check that headings work as a standalone table of contents, since a lot of readers scan rather than read top to bottom. The second pass is accuracy: I walk through every instruction myself, step by step, exactly as written, because it's very easy to skip a step mentally when you already know how something works. I've caught missing steps this way that would have completely blocked a reader. The third pass is language: cutting unnecessary words, checking terminology is consistent with our style guide and glossary, and making sure I haven't used two different terms for the same thing. I use Vale for automated style and terminology checks before a human review, which catches a lot of small inconsistencies without needing a person to spot them manually. Before publishing, I ask someone unfamiliar with the feature, often someone from a different team, to follow the doc cold and tell me where they got stuck.

How do you decide what level of detail to include for different audiences?

I start from the task the reader is trying to complete, not from everything I know about the feature. A developer integrating an API needs request and response examples, authentication details, and error codes; they don't need the backstory of why the endpoint was designed a certain way unless it affects how they use it. An end user reading a help article needs plain steps and screenshots, and technical implementation detail would just get in the way. When I'm not sure who the audience is, I ask the requester directly rather than guessing, because writing for the wrong reader wastes the effort twice, once to write it and once to rewrite it. For mixed audiences I sometimes split a document: a quick-start section for someone who wants to get moving immediately, and a reference section underneath for someone who needs the full detail. I also pay attention to what support tickets and community forum questions are actually asking, because that tells me where the real confusion is happening rather than where I assume it is. If nobody has ever asked a question about a section, that's often a sign it can be shorter.

How do you keep documentation up to date as a product changes quickly?

The biggest lever is making documentation part of the release process rather than something that happens after the fact. I push for docs to be a checklist item before a feature ships, not a follow-up task, because docs written after launch consistently get deprioritised once the team moves on to the next thing. I work in Markdown with our docs stored alongside the codebase in Git, so a documentation update can go through the same pull request as the code change, and reviewers see both together. For areas that change often, like API reference docs, I generate as much as possible directly from the OpenAPI spec rather than hand-writing content that will drift out of sync. I also do a periodic audit, going through the highest-traffic pages every quarter and checking they still match the current product, because even a good process misses things occasionally. When I find outdated content during support or feedback review, I fix it immediately rather than filing it away for later, since a small fix takes minutes and a backlog of stale docs takes days to work through.

Tell me about a time you had to write documentation with incomplete or conflicting information from your sources.

I was documenting a data export feature where two engineers gave me different answers about what happened to deleted records: one said they were excluded automatically, the other said they were included unless manually filtered. Rather than picking one answer and hoping it was right, I set up a quick test myself: I created a record, deleted it, and ran the export to see what actually happened. That settled the factual question in about fifteen minutes, faster than continuing to go back and forth over Slack. It turned out neither engineer was fully right: deleted records were excluded by default but reappeared if a certain filter was set, which was an edge case nobody had mentioned. I documented that specific behaviour clearly, including the edge case, and flagged it to the team as something worth confirming was intentional, since it wasn't obvious it should work that way. The lesson I took from it is that when sources disagree, testing the actual product is often faster and more reliable than trying to arbitrate between two people's memories of how something was built.

Describe a time you had to push back on an engineer or stakeholder about the content or structure of a document.

An engineer wanted the API reference to include every internal parameter available on an endpoint, including several that were used for internal debugging and weren't meant for external developers. My concern was that including them would create support tickets from developers trying to use parameters that weren't actually supported for external use, and it would clutter the page for the parameters people needed. I didn't just say no: I pulled up three examples from our support queue where similar undocumented-but-visible parameters had caused confusion in another part of the docs, to make the case concrete rather than a matter of opinion. I proposed a compromise: keep the public reference clean, and maintain a separate internal-only page linked from our engineering wiki for anyone on the team who needed the full parameter list. The engineer agreed once they saw the support ticket pattern, and the internal page turned out to be useful for onboarding new engineers too. I've found that pushback lands better when it's backed by a specific example of what went wrong before, rather than a general preference for simplicity.

Tell me about a time your documentation directly reduced support tickets or user confusion. How did you know it worked?

Our support team flagged that a specific setup step, connecting a third-party calendar integration, was generating a steady stream of tickets, roughly fifteen a week according to their tagging system. I read through a sample of the tickets and noticed the existing doc assumed the reader already knew where to find their calendar's API key, which wasn't obvious at all for less technical users. I rewrote the section with a screenshot-led walkthrough for the two most common calendar providers, added a troubleshooting section addressing the three specific error messages that came up most often in the tickets, and moved the doc higher in the help centre's search results by updating the title to match the phrasing customers actually used when searching. I asked support to tag tickets related to that flow separately for the following six weeks so we could measure the actual impact rather than assume it worked. Tickets for that specific issue dropped from about fifteen a week to roughly four, and the ones that remained were different problems, not the confusion the rewrite addressed. Tying the fix to a measurable before-and-after was what made the improvement provable rather than anecdotal.

What tools and formats do you use for writing and publishing documentation?

My day-to-day writing is mostly in Markdown, which I prefer for technical docs because it's lightweight, works well with version control, and keeps formatting from getting in the way of the actual content. I've worked with docs-as-code setups where documentation lives in Git alongside the product codebase, changes go through pull requests, and a static site generator, I've used both Docusaurus and MkDocs, builds the published site from the source files. For larger, more structured documentation sets I've used Confluence, which works well for internal knowledge bases but is less suited to versioned, publicly published docs in my experience. For API documentation specifically, I work from OpenAPI or Swagger specs where possible, since generating reference content directly from the spec keeps it accurate as the API changes, rather than hand-maintaining a document that can drift. I use Vale for automated linting against our style guide, and Snagit for annotated screenshots when a visual walkthrough is more useful than text alone. I'm comfortable picking up a new toolchain quickly: what matters more to me than any specific tool is understanding the underlying workflow, source control, review process, and publishing pipeline, because that structure transfers across tools.

Walk me through how you would structure documentation for a new API.

I'd start with a getting-started guide that takes a developer from zero to their first successful API call in the fewest possible steps: authentication, a single example request, and the expected response, nothing else. Developers evaluating whether to use an API often decide within the first few minutes based on how quickly they can get something working, so that first page carries a lot of weight. After that I'd structure the reference documentation by resource or endpoint, with consistent sections for each one: description, required parameters, a request example, a response example, and common error codes with what causes them. I'd keep the reference content as close to auto-generated from the OpenAPI spec as possible, so it doesn't drift from the actual API behaviour. Alongside the reference, I'd add task-based guides for common use cases that combine multiple endpoints, since a developer building a real integration usually needs to know how several calls work together, not just each one in isolation. I'd also include a changelog and a clear versioning policy, since API consumers need to know what changed and whether it will break their existing integration before they update anything.

How do you validate that documentation is technically accurate before publishing?

Wherever I can, I follow every instruction myself exactly as written, using a clean test environment rather than one where I already have things configured from previous testing, because a clean environment catches missing setup steps that an already-configured one hides. For anything involving code samples, I actually run the code rather than trusting that it looks correct, since a single typo in a sample can block a reader for much longer than it took me to make the mistake. For more complex technical claims I can't verify hands-on, like details of an internal architecture, I ask the engineer who built it to review the specific paragraph rather than the whole document, because a focused review request gets a more careful check than 'can you look this over' on a long page. I keep a short list of open questions during drafting rather than guessing and hoping I got it right, and I don't publish until those are resolved. After publishing, I treat support tickets and reader feedback as an ongoing accuracy check: if multiple people get stuck at the same step, that's often a sign the instructions were unclear or something changed in the product since the doc was written, not that the readers made a mistake.

Technical Writer

Technical Writer interviews test whether you can turn a complex process or system into documentation that a reader can actually follow without help, and whether you can work with engineers and product teams to get the details right. Interviewers want to see a structured writing process, comfort learning unfamiliar subject matter quickly, and judgement about what belongs in the docs versus what should stay out. Expect questions about your writing samples, how you handle ambiguous or incomplete source material, and how you decide what a reader actually needs to know. This guide covers the questions asked most often and the answers that show you can produce documentation people actually use.

For general interview preparation tips, read our guide to common interview questions.

Prepare further

How to ace the behavioural interview (STAR method)How to prepare for a technical interview

Common Technical Writer Interview Questions

Behavioural Interview Questions for Technical Writer Roles

Technical Questions for Technical Writer Candidates

What Hiring Managers Look for in Technical Writer Interviews

What hiring managers really look for in Technical Writer candidates:

Hands-on verification habits. The strongest candidates test instructions and code samples themselves rather than trusting that they look correct. Ask how they validate accuracy before publishing.
A structured writing and editing process. Look for multiple distinct passes, structure, accuracy, language, rather than a single read-through before submitting.
Comfort learning unfamiliar technical subject matter. Ask for an example of documenting something they did not initially understand, and how they closed the knowledge gap.
Judgement about audience and scope. Strong writers tailor detail to the reader's task rather than including everything they know. Ask how they decide what to leave out.
Evidence that documentation changes measurable outcomes. Candidates who can point to a support ticket drop or a specific before-and-after metric are thinking about impact, not just output.

Questions to Ask Your Interviewer

→How closely does the documentation team work with engineering, and at what point in the development process do writers usually get involved?
→What tools and publishing workflow does the team use, and is documentation stored alongside the codebase?
→How is documentation quality or impact measured here, support tickets, user feedback, page analytics?
→How many products or features would I be responsible for documenting, and how is that workload typically split across the team?
→What does the review and sign-off process look like before something gets published?

Practise These Questions Before Your Interview

The mock interview tool builds a practice session around a specific job posting and your background, so you rehearse the questions most likely to come up.

Start Practising

Free on your first tracked role.

Related Roles

Available in Other Languages

Français Español