Technical writer, engineering role-specific interview questions

As asked

Your public quickstart works on your laptop but fails for many new users with authentication and dependency errors. How do you diagnose and fix it?

Sample answer outline

Start by reproducing in a clean environment, ideally a fresh container or CI job with no cached credentials. Check every assumed prerequisite: package manager version, environment variables, API key scopes, region defaults, network calls, and copy-paste commands. The fix should include clearer errors, preflight checks, pinned or bounded dependency versions, and an automated smoke test that runs the published quickstart. Strong DevRel candidates explain how they collect failure reports without shaming users and how the findings become product improvements. A common miss is only editing the prose while leaving the fragile path intact.

Expect these follow-ups

• What would your quickstart CI test actually run?
• How do you decide between adding explanation and simplifying the product flow?
• What telemetry would you add to know where developers drop off?

As asked

You are asked to document a new API, but the only source material is the implementation, tests, and a few Slack threads. How do you produce accurate docs?

Sample answer outline

A strong writer triangulates from code, tests, and engineers rather than rewriting Slack notes. Start by identifying the audience, main tasks, authentication path, request and response shapes, error cases, limits, and versioning behaviour. Run the examples against a real or local environment so the docs are executable, not aspirational. The candidate should push for missing product decisions where the code is ambiguous. Interviewers look for accuracy discipline: docs review, changelog links, owned examples, and a maintenance path when the API changes.

Expect these follow-ups

• What do you do when the implementation and the intended behaviour disagree?
• How do you test code samples in docs?
• Which parts belong in reference docs versus a tutorial?

As asked

You join a team mid-sprint and the lead engineer drops you into a Swagger file and a Postman collection for a payment API that ships in three weeks. Walk me through exactly what you do in the first two days.

Sample answer outline

Strong answers mention reading the OpenAPI spec top to bottom first, running every endpoint in Postman to verify the spec matches actual behavior, flagging discrepancies immediately, and setting up a lightweight doc skeleton before writing prose. Candidates should mention identifying the primary user persona (developer integrating the API) and scoping the happy path first before edge cases.

Expect these follow-ups

• What do you do when the Postman collection and the spec disagree on a field name?
• How do you prioritize which endpoints to document first?

As asked

If I hand you an OpenAPI 3.1 file and ask you to assess it before you generate any docs from it, what are the five or six things you look at first?

Sample answer outline

Strong answers cover: meaningful summary and description fields (not just auto-generated names), proper schema names rather than inline anonymous objects, example values that reflect realistic payloads, correct use of $ref to avoid duplication, complete error response definitions, and tags that map to a logical grouping the reader would recognize. Candidates should flag that generated docs are only as good as the spec.

Expect these follow-ups

• How do you push back on engineers who say description fields are optional?

As asked

What is your process for writing changelog entries, and what is the difference between a changelog entry that helps a developer upgrade confidently versus one that just lists commits?

Sample answer outline

Strong answers describe structuring entries by impact (breaking changes first, then new features, then fixes), linking directly to the changed reference page and migration guide, and writing from the developer's perspective: what they need to do, not what the team did internally. Candidates should mention following Keep a Changelog conventions or a documented in-house format, and avoiding commit-message dumps.

Expect these follow-ups

• How do you get engineers to submit useful release notes rather than one-line commit messages?

As asked

I often see developer docs that try to be both at once and end up being neither. How do you draw the line between reference content and tutorial content, and what are the failure modes of each?

Sample answer outline

Strong answers draw the Diátaxis-style distinction: reference is information-oriented and complete (every parameter, every return type), tutorials are learning-oriented and opinionated (this is the one way we will do it today). Reference fails when it omits why or when to use something. Tutorials fail when they branch on every option instead of committing to a single path. Candidates may mention how-to guides as a third category distinct from tutorials.

Expect these follow-ups

• How do you handle a tutorial that needs to show two different authentication methods?

As asked

Assume the docs repo lives in GitHub alongside the product code. Describe your actual Git workflow from the moment you start a doc update to the moment it merges.

Sample answer outline

Strong answers describe branching from main, using a consistent branch naming convention (docs/issue-123-payment-api-errors), writing a clear PR description that links to the related engineering issue, squashing trivial commits before review, and knowing how to resolve merge conflicts in Markdown without corrupting front matter. Candidates should mention tagging the right reviewer (engineer vs. fellow writer) depending on what is being reviewed.

Expect these follow-ups

• How do you handle a PR where an engineer wants to change your wording in a way you disagree with?

As asked

Most quick-start guides are not quick. What is your process for writing one that a developer can complete in under ten minutes, and what are the most common mistakes that make them fail?

Sample answer outline

Strong answers note that a quick-start must commit to one path (one OS, one language, one auth method) and defer all alternatives to other guides. The developer should reach a working output (a successful API call, a running server, a visible UI) within ten steps. Common failures: prerequisite steps that themselves have prerequisites, environment setup that is glossed over, and sample code that does not actually run because it references placeholder values the developer has to hunt for.

Expect these follow-ups

• How do you test whether your quick-start is actually doable by a new developer?

As asked

You are writing the README for a Node.js SDK that wraps your company's REST API. What sections does it need, in what order, and what are the failure modes of most SDK READMEs you have seen?

Sample answer outline

Strong answers list: a one-sentence description of what the SDK does, installation (npm command), authentication setup with a working code snippet, a minimal working example (not Hello World, but a realistic first use case), a link to full reference docs, supported runtime versions, and a contributing guide link. Common failures: READMEs that start with a feature list nobody asked for, installation instructions that assume global npm config the developer has not set, and examples that import from an internal file path.

Expect these follow-ups

• How do you handle a README that needs to cover both CommonJS and ESM usage?

As asked

Walk me through an API reference page or guide you found in poor shape and substantially improved. What was wrong with the original, what did you change, and how did you know the new version was better?

Sample answer outline

Strong answers are specific: the original lacked example request bodies, response schemas were undocumented, error codes pointed to a 404 page. The writer added a complete cURL example, documented every field in the response, rewrote the description from engineer-speak to user-task framing, and measured improvement through support ticket volume or page rating scores. Vague answers about 'making it clearer' without specifics are weak.

Expect these follow-ups

• How long did it take, and what stopped you from fixing it sooner?

As asked

Describe a specific situation where an engineer or team was hard to get information from, and explain what strategies you used to get what you needed to write accurate documentation.

Sample answer outline

Strong answers describe concrete tactics: attending sprint reviews to catch demos without scheduling separate meetings, reading source code comments and tests to draft a skeleton that the engineer only had to correct rather than write from scratch, or asking highly specific questions via async comments rather than open-ended 'can you explain this?' Strong answers also acknowledge when the best approach is a short call versus async.

Expect these follow-ups

• How do you handle a situation where the engineer's explanation conflicts with what the code actually does?

As asked

Describe a product launch where documentation had to ship simultaneously with the product but there was not enough time to document everything. How did you decide what to prioritize?

Sample answer outline

Strong answers describe a triage approach: shipping the happy-path quick-start and the minimal reference (endpoints developers would call on day one), explicitly labeling other sections as 'coming soon' rather than shipping incomplete content without notice, and creating a post-launch doc backlog with owners and dates. They should describe what they cut and why, rather than claiming they somehow documented everything.

Expect these follow-ups

• What did you end up shipping that you wish you had cut, and what did you cut that you wish you had shipped?

As asked

You have written a draft of a complex feature's documentation and the engineer who built it keeps pushing back your review meeting. The launch is in a week. What do you do?

Sample answer outline

Strong answers describe escalating through a manager (theirs or yours) only after trying multiple async approaches first, sending the draft with specific numbered questions rather than 'please review this', identifying a secondary expert (someone who tested the feature, the PM, the engineer's teammate), and clearly documenting the risk to the launch if the review does not happen. They should not describe just shipping unreviewed content.

Expect these follow-ups

• What do you write at the top of a page that shipped without an expert review?

As asked

Most developers scan documentation rather than read it from top to bottom. How does that change how you structure and write every page?

Sample answer outline

Strong answers describe: putting the most important information and the working code sample in the first screenful, using descriptive headings that work as navigation labels not just section titles, keeping paragraphs to three sentences or fewer, using tables for comparisons and lists for steps, and front-loading parameter descriptions with type and whether required before explaining details. They note that a developer who lands on a reference page via search is looking for one field name or one error code, not an introduction.

Expect these follow-ups

• How do you write a conceptual explanation page (not a reference) for a scanning reader?

As asked

You are writing product copy for a settings flow that will ship in 12 languages. What do you do differently from day one?

Sample answer outline

Write concise but complete strings that do not depend on English word order, humour, or visual position. Avoid concatenated fragments because many languages need different grammar, gender, pluralisation, or sentence order. Provide translators with context: screenshots, character limits, tone notes, and variable meanings. Work with design to allow text expansion and with engineering to support ICU-style plural and select rules. Candidates often mention translation late; senior UX writers design the content model and review workflow so localisation is not a last-minute string export.

Expect these follow-ups

• How do you handle a button label that grows by 40 percent in German?
• What context should a translator receive for an error message?
• How would you review machine-translated UX copy?

As asked

Engineering is shipping a breaking API change next week. What do you need from them, and how do you write release notes that reduce customer pain?

Sample answer outline

The answer should start with facts: what changes, who is affected, when it happens, whether there is a compatibility window, and how users detect usage of the old behaviour. Good release notes lead with impact and required action, then provide migration steps, examples before and after, deadlines, and support paths. The candidate should ask engineering for testable snippets, error messages, and rollback or opt-out details. Strong writers coordinate with customer success and DevRel so the message reaches the right users. A weak answer turns the release note into a celebratory feature announcement and hides the breaking part.

Expect these follow-ups

• What if engineering says the change is too obvious to need migration docs?
• How do you handle a breaking change that only affects 2 percent of users?
• What belongs in email versus changelog versus reference docs?

As asked

If you were setting up a brand-new docs-as-code pipeline for a team of twenty engineers, what tooling would you choose, how would you structure the repo, and what would a PR workflow look like from a writer's perspective?

Sample answer outline

Strong answers propose a static site generator (Docusaurus, MkDocs, or Sphinx) matched to the team's existing language stack, a dedicated docs repo or a docs/ directory in the main monorepo, linting via Vale or markdownlint on PR, and a review process that requires at least one engineer SME approval plus a writer approval. Candidates should mention CI publishing (Netlify, GitHub Pages, or internal host) and how they handle versioning for multiple API versions.

Expect these follow-ups

• How do you handle a situation where engineers keep merging PRs without updating docs?

As asked

You want to introduce Vale into a docs repo that has 400 Markdown files written by six different engineers over two years. How do you roll it out without breaking everyone's workflow or creating a massive backlog of lint errors?

Sample answer outline

Strong answers describe starting with a minimal .vale.ini that sets MinAlertLevel to error only, choosing one style package (Microsoft or Google) rather than combining several, adding .vale.ini to a feature branch first, and running a bulk baseline pass to categorize existing violations before enforcing them in CI. Candidates should mention communication: announcing the linter, giving the team a one-sprint fix window, and ignoring legacy files via glob patterns until they are next touched.

Expect these follow-ups

• What rule categories would you configure as warnings versus errors?

As asked

You have documented REST APIs for two years. Your new team ships a GraphQL API. What changes in your documentation strategy and what stays the same?

Sample answer outline

Strong answers note that GraphQL self-documents through its schema (introspection) so tooling like SpectaQL or graphql-docs can generate reference docs, but the harder work is conceptual: explaining the query language, variables, fragments, and mutation side effects. The biggest gap in REST to GraphQL transition is teaching users how to compose queries rather than listing endpoints. Authentication, rate limiting, and error handling documentation remain similar in structure. Candidates should note that GraphDoc (graphdoc npm package) is largely unmaintained since 2020 and should not be recommended for new projects.

Expect these follow-ups

• How do you document breaking changes when a GraphQL type is deprecated?

As asked

A product manager gives you greenfield authority over the navigation and content structure for a developer portal that will cover four APIs, two SDKs, and a CLI tool. How do you figure out what the structure should be?

Sample answer outline

Strong answers describe starting with user research (even lightweight card sorting or tree testing with three to five developers), mapping job stories to content types, and separating the portal into at minimum: conceptual overviews, quick-start guides, full API reference, tutorials, and a changelog. Candidates should mention avoiding the classic mistake of organizing docs by internal team ownership rather than by user task.

Expect these follow-ups

• How do you handle content that belongs to two different user journeys?

As asked

Your docs include Python, Node.js, and Go code samples. The SDK ships a major version every six months. How do you prevent the docs from going stale?

Sample answer outline

Strong answers discuss executable code samples that run in CI (doctest for Python, runnable test files for Node/Go), generating samples from a tested reference implementation rather than hand-writing them, using version tabs or conditional includes in the static site, and adding a deprecation notice workflow triggered by a semantic-version bump in the SDK repo. Candidates should acknowledge the tradeoff between readability and testability.

Expect these follow-ups

• What do you do when CI fails because a code sample calls an API that changed?

As asked

Explain how Docusaurus snapshot versioning works under the hood, and describe a scenario where you would deliberately choose not to use it.

Sample answer outline

Strong answers explain that running 'docusaurus docs:version X.Y' (via npm run or npx) copies the current docs/ tree into a versioned_docs/version-X.Y/ folder (note the version- prefix) and freezes the sidebar into versioned_sidebars/version-X.Y-sidebars.json, then serves each version from its own URL prefix. Candidates should note when to avoid it: if the API changes every sprint, snapshot versioning creates an unmanageable number of frozen trees; instead, a single latest-only site with a migration guide per version is often cleaner. They should also mention the maintenance cost of fixing security issues in old snapshot trees.

Expect these follow-ups

• How do you handle a hotfix to a deprecated version's documentation?

As asked

In a Markdown-based docs system, what YAML front matter fields do you define on every page, and what breaks or degrades if a field is missing?

Sample answer outline

Strong answers cover: title (used in nav, browser tab, og:title), description (used in SEO meta and search snippets), sidebar_position or weight (controls nav order), slug or id (stable URL), last_updated or date (used by changelog feeds), and tags or keywords (used by site search). Candidates should note that missing description defaults to the first paragraph, which is often wrong for SEO, and missing sidebar_position causes alphabetical ordering which may not be logical.

Expect these follow-ups

• How do you enforce front matter completeness across 500 Markdown files?

As asked

The authentication section of your REST API docs and your SDK getting-started guide need to explain the same OAuth 2.0 flow. How do you avoid maintaining two copies?

Sample answer outline

Strong answers describe content reuse strategies: MDX or RST includes that pull a shared source snippet, a separate auth-concepts.md file that both pages link to rather than inline, or a doc snippet component that renders in both contexts. Candidates should note the tradeoff: deep transclusion makes the content harder to read in isolation and harder to search locally. They should explain how they pick the right level of reuse.

Expect these follow-ups

• What happens to your shared snippet when one audience needs a slightly different version of the same content?

As asked

Your team is deciding between Swagger UI and Redoc for the API reference landing page. What are the concrete differences in user experience and customization, and how do you make the call?

Sample answer outline

Strong answers note: Swagger UI has an integrated try-it-out console (interactive), while Redoc is read-only but renders schemas in a three-panel layout that most developers find cleaner for reference reading. Redoc handles deep nested objects better. Swagger UI is harder to theme consistently with a brand. For exploration-heavy use cases, Swagger UI wins. For documentation-first teams, Redoc or Stoplight Elements are cleaner. Candidates should mention Mintlify or ReadMe as hosted alternatives worth considering.

Expect these follow-ups

• How do you add authentication credentials to a Swagger UI try-it-out session without exposing a real key?