Technical Writer Interview Questions

Option B is the strongest: it names the Diatáxis framework (the industry-standard vocabulary for this distinction), explains the purpose principle (docs differ by purpose, not length), gives a memorable formulation of the tutorial's paradox ("the reader follows steps they may not understand yet — that's intentional"), provides concrete examples, states the practical consequence of mixing them, and covers all four Diatáxis types — showing comprehensive documentation knowledge. The Diatáxis framework (Daniele Procida, 2017–2021): Tutorial — learning-oriented. The reader is a beginner who needs to be taught. The writer's job is to ensure success and build a mental model. Analogy: teaching a child to cook — you choose safe, simple ingredients and techniques. How-to guide — task-oriented. The reader is a competent user who needs to accomplish a goal. Assumed context. No explanation of why — just how. Analogy: a recipe card. Reference — information-oriented. Exhaustive, accurate, structured for scanning. API documentation is reference. The tone is neutral, not pedagogical. Explanation — understanding-oriented. The why behind design decisions, trade-offs, architectural choices. Not instructions. Analogy: a blog post explaining why a library made a specific design choice. Why does this matter for interviews? It shows you think systematically about user needs before writing. Good technical writers apply this framework to decide what document to write, which prevents the most common documentation failure: one document that tries to be everything and serves no one well.

Option B is the strongest: it structures the answer into three precisely named dimensions (Accuracy / Usability / Findability), gives both quantitative and qualitative signals for each, names specific metrics with definitions, identifies the most important single metric (support ticket deflection), and provides a concrete user testing methodology (give a user a task + docs, observe completion). Documentation quality metrics vocabulary: Task completion rate — the percentage of users who can successfully complete a target task using only the documentation, without additional help. Measured via usability testing. Target: 80%+ for critical user journeys. Time on task — how long it takes a user to complete a task using the docs. Compared against expected duration. Significantly longer than expected → the doc has friction. Significantly shorter with errors → the user skipped important steps. Doc-to-code drift — the time between a code change and the corresponding documentation update. Tracked by linking doc reviews to pull requests. High drift = unreliable docs = user distrust. Support ticket deflection rate — the reduction in support tickets attributable to documentation improvements. Formula: (tickets before doc update − tickets after) ÷ tickets before. Powerful for making the business case for documentation investment. Exit rate on tutorials — the percentage of users who leave a tutorial page without completing it. High early exit rate (first 20% of the page) = the entry point is wrong (wrong audience, wrong prerequisites). High late exit rate = the tutorial hits a wall (a step that fails). Self-review rubric — a checklist technical writers use before publishing: first sentence states the purpose; prerequisites are listed; every step produces a visible result; errors are documented with their fixes; the "happy path" is tested against the current release.

Option B is the strongest: it opens with specific stakes (400+ integrators, breakage risk), describes a multi-stakeholder discovery process, shows audience segmentation resulting in three separate documents by needs, names the structural template elements and explains the purpose of each, describes a three-type review cycle including external user testing, and closes with a specific, quantified outcome (60% reduction in migration support tickets). This is STAR format with documentation vocabulary layered throughout. How to answer "walk me through a doc you wrote" questions: Setup — what was the context, what were the stakes? Quantify the audience and the risk. Discovery — how did you learn what to write? Stakeholder interviews, existing support tickets, developer feedback? Audience analysis — who are the readers? What do they already know? What are they trying to accomplish? Did you write one doc or multiple for different segments? Structure/Drafting — what template did you use? How did you decide on the sequence of information? Review cycle — who reviewed for accuracy? Who tested it as a user? Did you do external testing? Measurement — how did you know it worked? Document the outcome with a number. Documentation structure vocabulary: Purpose statement — the first sentence of any doc. "After reading this, you will be able to [action] without [obstacle]." Prerequisites — what the reader must have or know before starting. Missing prerequisites are the single most common cause of tutorial failure. Expected output — what the reader should see at the end of each step. Enables the reader to verify they're still on track. Error table — a two-column table: error message | cause and fix. Converts support tickets into self-service. Naive user test — giving the doc to someone who has no pre-existing context and observing where they get stuck.

Option B is the strongest: it opens with the crucial reframe (accuracy is a process problem, not a people problem) which immediately signals seniority, describes a concrete PR template approach with three explicit options (avoiding the binary "did you update the docs?"), names the "doc delta backlog" as a specific artefact, describes the doc freeze pattern for releases, introduces the doc ownership model and distinguishes ownership from responsibility, and closes with the measurement approach (doc-to-code drift). Engineering–documentation collaboration vocabulary: Definition of done (DoD) — the team-agreed criteria that define when a feature is complete and shippable. Adding documentation to the DoD means docs are not an afterthought but a sprint delivery condition. "The feature is done when the code is merged, tested, and the documentation is updated." PR (pull request) template — a structured form that developers fill out when submitting code for review. Adding a documentation impact field makes doc debt visible at the point where it's cheapest to address (while the author still has context). Doc freeze — a period before a major release during which the documentation is locked for final review. Prevents last-minute changes that introduce inaccuracies. Analogous to a code freeze. Doc delta — the set of documentation changes required as a result of code changes in a sprint or release. Maintained as a backlog item list by the technical writer. Doc-to-code drift — time elapsed between a code change and its corresponding documentation update. Low drift = accurate docs. High drift = unreliable docs that damage developer trust. Documentation ownership vs. responsibility — ownership = the engineer has a stake in the doc's quality and a voice in its content. Responsibility = the engineer is obligated to do a task. Ownership drives better collaboration because it frames the relationship as partnership.

Option B is the strongest: it lays out four explicit phases with names, introduces the valuable practice of reading the existing spec to find gaps (not just to understand the API), highlights the specific insight of making intentional errors (documenting error responses is often the most valuable part of API docs), names the exact interview questions to use, specifies the reference doc structure by section, makes the reference/explanation separation explicit, and describes the post-publication tracking loop. API documentation vocabulary: OpenAPI / Swagger specification — a machine-readable JSON/YAML definition of a REST API: endpoints, methods, parameters, request/response schemas, authentication, error responses. The spec is the source of truth for reference docs. Tools: Swagger UI, Redoc, Stoplight. Quickstart guide — a self-contained, copy-pasteable example that produces a successful API response in under 5 minutes. The most impactful single page in any API docs. Should cover: prerequisites, authentication, a complete request and response, next steps. Endpoint reference — the per-endpoint documentation: HTTP method, URL pattern, path/query/header parameters (name, type, required/optional, description), request body schema, response schemas (200 and all error codes), example request/response pair. Error code documentation — one of the most underwritten sections in API docs. For each error code: HTTP status, error code string, what caused it, and what the integrator should do to fix or handle it. Reduces support tickets dramatically. Changelog — a versioned history of API changes. Critical for integrators who need to know what broke between versions. Includes: version number, date, breaking changes (highlighted), new features, deprecations, and migration notes. Rate limiting documentation — often missed: request limits per second/minute/day, HTTP headers that communicate rate limit state (X-RateLimit-Remaining), and how to handle 429 Too Many Requests.

Sarah needs to push the developer beyond a superficial statement. Option 1 addresses a critical missing piece – error handling. Options 2 and 3 demonstrate an overly simplistic or dismissive response, while option 4 focuses on tangential information (design documents) rather than core documentation requirements. A good technical writer probes for details that ensure the reader understands potential issues.

David's original message lacks precision. Option 1 uses more formal and technical language appropriate for documentation – 'resolved an issue'. Option 2 provides a slightly better explanation but still avoids specific terminology. Options 3 is too vague, while option 4 overstates the functionality (not all users).

The original statement is too vague and doesn't convey the severity or technical nature of the issue. Option 1 uses stronger language ('critical vulnerability') and clearly explains the impact. Options 2 & 3 are still too informal, while option 4 repeats information from the original but without adding value. Using precise terminology improves clarity for developers and stakeholders.

The core goal of a knowledge base article is to help *users* solve problems. Option 0 focuses on user empowerment – providing tools and information for self-help. The other options represent different documentation types (root cause analysis, IT support guides, or reporting). A good troubleshooting guide prioritizes the user's ability to fix things themselves.

While announcing the endpoint itself is a start, Option 1 provides crucial context about *what* the endpoint does. The response format (JSON object) is essential information for developers to understand how to consume the API. Options 2 and 3 are promotional or cautionary, not descriptive documentation. Option 4 is too vague.

The key here is to understand *why* the comment was made. Option 1 highlights the need for clarification and a concrete solution – refactoring based on feedback. The other options are passive or unhelpful; simply agreeing, offering vague suggestions, or assuming action won't resolve the issue.

The original statement is too high-level. Option 1 provides a concrete detail about the implementation (100 requests per minute), which is essential for developers to understand the limits and potentially test them. Options 2 & 3 are valid explanations of *why* rate limiting is important, while option 4 is dismissive and doesn't convey any technical information.