Technical Writer Interview Exercise: Turn an API Spec into Tested Developer Documentation

A technical writer interview exercise may give you an API description that looks complete until you try to write the first working request. The path and response schema are there, but the authentication scope, missing-record behavior, or example values are unclear. The strongest submission does not hide those gaps behind polished prose. It turns each claim into a testable request, observed result, or explicit question for the API owner.

Cockroach Labs publicly describes technical-writer exercises involving learning a technical concept, documenting it, and discussing the result with an engineer; GitLab's technical writer role emphasizes docs-as-code collaboration. Those sources establish relevant skills, not a universal hiring format. This article's API and exercise are original.

The short answer: separate specification, observation, and unknowns

Start by identifying the reader's job: what must a developer accomplish, and what do they need before the first successful call? Extract the operation, server, auth, parameters, request body, success schema, errors, limits, and version. Turn the happy path and at least two failure paths into runnable probes in an authorized sandbox. Compare actual status, headers, and JSON with the written contract. Draft the task path and reference from verified facts; put unresolved questions in a short decision log for the owner rather than manufacturing answers.

The OpenAPI Initiative's guidance distinguishes concise summaries, fuller descriptions, and examples. Examples should match their schemas, but schema validity alone does not prove the service returns them. A technically sound writer also checks what a request actually does, how a caller recovers, and whether the wording helps a first-time integrator use the endpoint without guessing.

Original exercise brief: document GET /v1/items/{id}

Fictional API, invented for practice. You receive the following abbreviated brief: “Fetch an item by ID. Use a bearer token. Success returns id, name, and status. An item may not exist.” No base URL, token scope, error schema, ID format, or rate-limit policy is supplied. You have a local mock service and 60 minutes to produce a developer-facing page and an uncertainty log. The exact timer is a practice constraint, not a claim about any employer's assessment.

Your first deliverable is a gap list, not finished prose. Ask whether id is numeric, opaque, or URL-encoded; whether the token must carry a particular scope; whether a missing item returns 404, 204, or something else; whether status has an enum; whether errors share a schema; and which environment and version the page covers. Ask what data is safe to use in an example. A fake api.example.com URL is useful for illustration but must be labeled as nonfunctional; otherwise a reader may copy it and mistake the failure for their own setup.

For this exercise, assume the mock owner explicitly approves: numeric IDs, bearer token demo-token only in the local fixture, 200 for item 42, 401 without a token, 404 for absent item 99, and 400 for malformed ID. These are fixture decisions, not properties inferred from OpenAPI or asserted about a production service. If an actual exercise does not provide those answers, leave the corresponding section marked for owner review instead of inserting this article's values.

Test the contract against a controlled service

The repo artifact for this article contains a small local HTTP fixture, run at 127.0.0.1 on an ephemeral port, and a four-case probe. It was executed for this guide; the results were 200, 401, 404, and 400 for the approved fixture inputs. This is a test of the fictional example, not a live third-party API. The difference matters: a mocked endpoint can validate your example's internal consistency but cannot establish actual product behavior.

The test matrix you would submit with the writing sample can be concise:

Case in local fixture	Request condition	Observed fixture result	Documentation implication
Success	Token and ID 42	200, item JSON	Show one copyable successful request and response.
Missing auth	No bearer token	401, error JSON	Explain token requirement and a safe next step.
Absent item	Token and ID 99	404, error JSON	Distinguish missing item from auth failure.
Invalid ID	Token and nonnumeric ID	400, error JSON	State the agreed ID format and validation failure.

The local fixture printed {"id":42,"name":"Notebook","status":"active"} for the success case, and the tests asserted the exact status and body for all four cases. In a real work sample, retain the command, environment, API version, timestamp, response headers, and sanitized output. Do not publish access tokens, private customer IDs, or full server logs just to prove you tested. If the interviewer does not allow network calls, state which checks are static schema checks and which behavior remains unobserved.

Turn the brief into a task path a developer can follow

The first screen of the documentation should answer “How do I retrieve an item?” before listing every schema field. A useful order is: purpose and prerequisite, environment and auth, copyable request, annotated success response, error and recovery table, field definitions, and links to related operations. If the base URL is unknown, do not disguise a placeholder as the production host. Use a clearly marked BASE_URL variable and tell the reader where to obtain the real value.

For the approved local fixture, a minimal example is:

curl --request GET \
  --url "$BASE_URL/v1/items/42" \
  --header "Authorization: Bearer $TOKEN"

Here BASE_URL points to the authorized local mock or sandbox, and TOKEN is supplied by that environment. The article's local fixture uses a demonstration token; a real documentation page should show how to obtain a scoped credential without embedding a usable secret. The sample response, validated against the fixture, is {"id":42,"name":"Notebook","status":"active"}. Explain that id is the requested numeric identifier and status is a string in this fixture. Do not invent a complete production enum from one observed value.

The OpenAPI parameter guidance makes the path-parameter contract explicit, including where the parameter appears and whether it is required. The response section can document each status separately. Add a full error example only after confirming its schema; a generic “request failed” paragraph is not enough for an integrator who must distinguish a missing item from an expired credential.

Show the before-and-after edit, not just the finished page

An interviewer wants to see your judgment. Consider the raw brief sentence: “Call GET with an ID and it returns item data. Errors are standard.” It is short, but it hides the endpoint version, authentication, ID format, response shape, and the meaning of “standard.” A revision should not merely expand the sentence; it should resolve or flag each missing claim.

A tested rewrite for the fictional fixture would be:

To retrieve one item, send GET /v1/items/{id} to the sandbox base URL with a bearer token. In this exercise, {id} is a numeric item ID. A successful request for item 42 returns HTTP 200 and an object containing id, name, and status. A request without a token returns 401; an absent numeric ID returns 404. These examples were checked against the local fixture, not a production API.

That paragraph is more useful because the route, auth, ID type, response, errors, and evidence boundary are visible. It still does not say how to acquire the token, what permissions it needs, whether status has other values, or how rate limiting works. Those remain open questions. In a real assignment, mark them for the API owner and explain which reader task each missing answer blocks.

The edit history can be a small review note: “Added task-first request; replaced vague error promise with verified 401/404 cases; left token scope and rate-limit behavior unresolved; requested owner confirmation.” This gives engineering an actionable review surface instead of a large polished document whose assumptions are hard to detect.

Error guidance should tell the reader what to do next

For each confirmed error, document a safe action. In the fictional fixture, 401 means the request lacked the expected bearer token; the reader should check that a token was supplied in the correct environment, not retry indefinitely. 404 means the requested numeric ID is absent in this mock; the reader should verify the identifier and whether it belongs to the correct environment. 400 means the path ID did not match the mock's numeric rule; correct the request format. Do not promise that every real API uses these exact semantics.

If a real spec lists 429 or 5xx, do not invent retry timing. Ask whether Retry-After is used, whether the operation is safe to repeat, and whether a timeout leaves an uncertain outcome. A GET is often safer to retry than a create operation, but providers can have behavior and rate-limit rules that matter. The writer's job is to make those rules accessible and correct, not to add generic exponential-backoff advice to every endpoint.

Use plain language before a code sample and keep the code syntactically plausible. If the response shows a field that the schema calls nullable, test both present and null cases when possible. If the spec has a required field but the sandbox omits it, do not “fix” the example silently: open a discrepancy with the API owner. Contract drift is valuable evidence, and documentation is one place that developers first detect it.

Review the submission as both writer and developer

Do one pass as a new reader: can you find the base URL, obtain authorized credentials, run the call, predict the shape of success, and recover from a common error without another conversation? Do a second pass as an engineer: do all parameter names, status codes, JSON types, and examples agree with the contract and observed behavior? Do a third pass as an editor: are headings task-oriented, sentences direct, links descriptive, and limitations visible near the claim they qualify?

Automation helps but cannot decide product truth. A linter can find malformed OpenAPI, a link checker can catch broken references, and a test can compare an example response to a schema. None can confirm that “active” means billable or that a token is safe to expose unless the owner establishes those semantics. GitLab's docs-as-code role description is a reminder that writers participate in review and version control; the practical implication is a small, reviewable diff with the evidence attached.

When you present the exercise, tell the interviewer what you tested, what you could not test, and what you would ask next. That shows more technical maturity than claiming the page is complete because the formatting looks professional. If the sample API is fictional, say so in the first line of your deliverable and keep demonstration values obviously nonproduction.

Final takeaway

The best technical writer work sample is an evidence trail, not merely a polished page: claim from the spec, authorized probe, observed result, reader-facing instruction, and an explicit owner question for what remains unknown.

Sources and Further Reading

• Cockroach Labs: Public technical-writer interview exercises
• GitLab Handbook: Technical Writer role
• OpenAPI Initiative: Parameters and payload
• OpenAPI Initiative: Documentation and examples
• OpenAPI Initiative: Operations and responses

Research note: Checked September 23, 2026. The items API, approved fixture behavior, and edit examples are original, fictional exercises. Four requests were executed against a local mock only; no production API behavior is claimed.