Technical writer, engineering domain knowledge interview questions

As asked

A developer asks you to clarify in the documentation whether to use PUT or PATCH for updating a resource. Explain the distinction and when each is correct.

Sample answer outline

Strong answers explain that PUT replaces the entire resource (the client must send all fields), while PATCH applies a partial update (only the fields being changed). They note that PUT is idempotent by spec while PATCH may or may not be depending on the implementation, and that documenting which fields are optional in a PATCH body is especially important because the behavior when omitting a previously set field varies between implementations.

Expect these follow-ups

• How do you document the behavior when a PATCH request omits a required field?

As asked

Walk me through the HTTP status codes that appear most often in REST API documentation and what each should tell a developer about what happened and what to do next.

Sample answer outline

Strong answers cover the most meaningful ones for API docs: 200 (success), 201 (created, document Location header), 204 (no content, common for DELETE), 400 (client validation error, document the error body), 401 (not authenticated, prompt to check credentials), 403 (authenticated but not authorized), 404 (resource not found vs route not found distinction), 409 (conflict, document the specific conflict condition), 422 (semantic validation error), 429 (rate limited, document Retry-After), 500 and 503 (server errors, document retry guidance).

Expect these follow-ups

• How do you document the difference between a 401 and a 403 so developers know which one to expect when their token expires?

As asked

List the authentication and authorization patterns you most frequently document in API references and describe what each requires in the docs.

Sample answer outline

Strong answers cover: API key in header or query param (document header name, key rotation), Bearer token (document format, expiry, refresh), OAuth 2.0 flows (auth code, client credentials, device flow), JWT (document claims, expiry, signing algorithm, how to validate), HMAC signature (document what is being signed and the exact algorithm), and mutual TLS (document the certificate requirements). They should note that documenting the security scheme in OpenAPI using securitySchemes connects authentication to each endpoint.

Expect these follow-ups

• How do you document the case where different endpoints require different authentication methods?

As asked

The concept of idempotency is important in REST API design. How do you explain it in documentation so that developers understand both what it means and why they should care when making API calls?

Sample answer outline

Strong answers define idempotency concretely (sending the same request multiple times produces the same server state as sending it once), explain why it matters in practice (network timeouts cause developers to retry, so non-idempotent operations like payment charges need an idempotency key), and document the idempotency key mechanism with a concrete example. They should note which HTTP methods are idempotent by spec (GET, PUT, DELETE) and which are not (POST).

Expect these follow-ups

• How do you document an endpoint that is designed to be safe to retry via an idempotency key?

As asked

Explain what JSON Schema is, how it relates to OpenAPI, and how you use schema definitions to generate or structure API reference documentation.

Sample answer outline

Strong answers explain that JSON Schema defines the structure and validation rules for JSON objects (type, required, format, enum, minimum, maximum, $ref for reuse), and that OpenAPI 3.0 used a restricted dialect of JSON Schema draft-04 with some proprietary extensions, while OpenAPI 3.1 aligns fully with JSON Schema 2020-12. Named schemas can be referenced ($ref) from multiple endpoints to avoid duplication. They should describe how to document additionalProperties, nullable fields (using 'nullable: true' in 3.0 or a null type union in 3.1), and discriminator patterns for polymorphic schemas.

Expect these follow-ups

• How do you document a oneOf or anyOf schema in a way developers can actually understand?

As asked

Beyond headings and bold text, which Markdown features do you rely on heavily in technical docs, and what are the syntax pitfalls that cause rendering problems?

Sample answer outline

Strong answers mention fenced code blocks with language identifiers, task lists, tables, definition lists (where supported), collapsible details/summary elements, and anchored headings for deep links. Common pitfalls: inconsistent blank lines inside lists that break list parsing, tabs vs spaces in code blocks, pipe escaping in table cells, and HTML tags inside Markdown that some parsers handle differently. They should mention that CommonMark standardized many ambiguities but platform parsers (Docusaurus vs GitHub vs MkDocs) still differ.

Expect these follow-ups

• How do you handle Markdown that renders correctly locally but breaks in the deployed docs platform?

As asked

Explain semantic versioning and describe how it should drive your versioning and deprecation documentation strategy.

Sample answer outline

Strong answers explain the MAJOR.MINOR.PATCH contract (breaking changes increment MAJOR, new features MINOR, fixes PATCH), note that a docs strategy tied to semver means major versions get a migration guide and a separate docs branch, minor versions get a changelog entry and updated reference, and patch versions get a changelog entry only. They should mention pre-release version suffixes and how to document alpha/beta APIs.

Expect these follow-ups

• How do you document an API that is at version 0.x and has no stability guarantees?

As asked

A new technical writer joins the team and has never used Git. What are the ten or so Git operations they need to understand to contribute to a docs-as-code repo effectively?

Sample answer outline

Strong answers list: clone, pull, checkout -b, status, add, commit, push, the PR-and-review cycle, merge conflict resolution in a text editor, and reset or restore for undoing local changes. They should note that for docs work, understanding rebase is useful but not critical, and that the most common mistake is committing to main instead of a feature branch. They should mention that force push to main is usually blocked by branch protection.

Expect these follow-ups

• What is the most common Git mistake you see from engineers and non-engineers contributing to a docs repo?

As asked

Walk me through the Diátaxis framework and explain how you apply it in practice when planning a new documentation project.

Sample answer outline

Strong answers describe the four types: tutorials (learning-oriented, done with the user), how-to guides (task-oriented, assumes competence), reference (information-oriented, complete), and explanation (understanding-oriented, conceptual). They note that most documentation failures come from mixing types in one page (a tutorial that tries to be a reference, a how-to that explains theory). They should give an example of how they would separate a current mixed-type page into Diátaxis categories.

Expect these follow-ups

• Where does a FAQ fit in the Diátaxis framework?

As asked

Which Content-Type values do you most frequently document for API request and response bodies, and what do developers need to know about each?

Sample answer outline

Strong answers cover: application/json (most common, document charset UTF-8), multipart/form-data (file uploads, document field names and file size limits), application/x-www-form-urlencoded (legacy form posts), application/octet-stream (binary, document format spec), text/event-stream (SSE for streaming responses, document reconnection behavior). They should note that OpenAPI documents content types in the requestBody and responses objects and that mismatch between Content-Type and body format is one of the most common developer errors.

Expect these follow-ups

• How do you document an endpoint that accepts both JSON and form-encoded bodies?

As asked

Some teams use changelog and release notes interchangeably. What is the meaningful distinction between them and when should you have both?

Sample answer outline

Strong answers explain: a changelog is a running cumulative record of all changes to a project, following the Keep a Changelog format with versions as headings, and is owned by the development team. Release notes are a per-release narrative document, often written for a broader audience (including non-technical users or customers), explaining what the release means for them rather than what changed in the code. They should note that a library uses a changelog while a SaaS product might use release notes on a blog and a changelog in its API reference.

Expect these follow-ups

• How do you automate changelog generation without ending up with unreadable commit dumps?

As asked

Compare Docusaurus, MkDocs, Sphinx, and Jekyll for technical documentation use cases. When would you choose each?

Sample answer outline

Strong answers note: Docusaurus (React-based, best for JS/TS communities, excellent versioning, MDX support, Algolia integration), MkDocs with Material theme (Python ecosystem, simple setup, Markdown-only, good for internal tools), Sphinx (Python-native, RST or MyST Markdown, reStructuredText directives, the standard for Python library reference generation), Jekyll (GitHub Pages native, Ruby, good for simple blogs but not ideal for large API doc sites). They should note that framework choice often follows team language familiarity rather than a neutral evaluation.

Expect these follow-ups

• How do you migrate from MkDocs to Docusaurus without breaking all your existing URLs?

As asked

OpenAPI allows vendor extensions using x- prefixed fields. What are they, what are common uses you have seen or applied, and what are the risks of relying on them?

Sample answer outline

Strong answers explain that x- fields are arbitrary key-value pairs ignored by spec-compliant tools but consumed by specific tooling (for example x-codeSamples used by ReadMe to inject language samples, x-logo for portal theming, x-internal to flag private endpoints). Candidates should note the risk: extensions are not portable, so switching doc tooling may silently drop them. They should recommend documenting which extensions are required by the current tooling in the repo README.

Expect these follow-ups

• How do you document an internal-only endpoint that should appear in internal dev tools but not the public portal?