For Technical Writer / Documentation Specialists ·
What you'll accomplish
By the end of this guide, you'll be able to use Claude to draft API reference documentation from an OpenAPI spec or endpoint description, generate working code examples, and write developer-friendly error documentation — without needing to write code yourself.
What you'll need
Before using Claude, you need input data. Collect one of these:
The more technical detail you provide, the more accurate Claude's output will be. Don't worry if you don't understand all of it — Claude will work with what you have.
What you should see: Raw technical material you can copy and paste into Claude.
Troubleshooting: Ask your engineering team for the OpenAPI spec — most REST APIs have one. It's usually at /swagger.json or /openapi.yaml in the API itself, or in the codebase.
Paste the endpoint spec and ask for developer documentation:
You are a technical writer documenting a REST API for developer users.
Here is the endpoint specification:
[paste OpenAPI YAML/JSON for one endpoint, or describe the endpoint]
Write developer reference documentation for this endpoint including:
1. Endpoint description (what it does, when to use it)
2. Request format (HTTP method, URL, headers, body parameters with types and descriptions)
3. Response format (success response structure with field descriptions)
4. Error codes (HTTP status codes this endpoint returns with explanations)
5. One example request (curl)
6. One example response (JSON)
What you should see: A well-structured API reference page with all required sections.
Once you have the endpoint documentation, request code examples:
Write code examples for the [endpoint name] API endpoint for:
1. bash (curl command)
2. Python (using the requests library)
3. JavaScript (using fetch with async/await)
Include: authentication header, correct Content-Type header, example request body, and basic error handling.
Endpoint details: [paste the endpoint spec or your generated documentation from Step 2]
What you should see: Three working code examples, each with authentication and error handling.
This is the critical step. Send the generated code examples to an engineer to verify:
Ask them to test the curl command against your sandbox environment if possible.
What you should see: Verified, working code examples that developers can copy-paste. Troubleshooting: If engineers make changes, update the examples and ask Claude to update the accompanying documentation to match.
Error documentation is frequently skipped. Use Claude to write it:
Write an error reference section for the [endpoint name] API endpoint. For each error code, include:
- HTTP status code
- Error type/name
- When this error occurs (specific conditions)
- How a developer should handle it in their code
Error codes this endpoint returns: [list the error codes from the spec, or ask your engineer]
What you should see: A complete error reference table that developers will actually use when debugging.
Full endpoint reference from spec:
Write developer API documentation for this endpoint. Include: description, request params with types, response fields, error codes, curl example, Python example. Spec: [paste spec]
Error documentation:
Write an error reference for these HTTP error codes from our API: [list codes]. Include: when it occurs, what caused it, how to fix it as a developer.
API getting started guide:
Write a "Getting Started" guide for our API. Audience: developer who has never used our API. Include: authentication, first API call (curl), common patterns, where to get help. API overview: [paste info]
Authentication documentation:
Write documentation for our API authentication. Method: [Bearer token / API key / OAuth 2.0]. Include: how to get credentials, where to include them in requests, token expiration, rotation. Details: [paste auth details]
Deprecation notice:
Write a deprecation notice for [old endpoint]. Include: sunset date, replacement endpoint, migration steps, what breaks if they don't migrate. Details: [paste]