Technical Writing

Technical Writing

This skill enables an AI agent to produce high-quality technical documentation across a range of formats — API references, user guides, getting-started tutorials, changelogs, architecture decision records, and more. The agent analyzes the target audience, structures information logically, applies consistent formatting standards, and ensures every document is accurate, scannable, and actionable.

Workflow

1. Identify Document Type and Audience Determine which type of document is needed (API reference, tutorial, user guide, changelog, architecture doc) and who will read it (beginner developers, experienced engineers, end users, stakeholders). Adjust vocabulary, depth, and assumed prerequisites accordingly. A tutorial for beginners should explain every step; an API reference for senior engineers should be terse and precise.

2. Gather Source Material Collect all relevant inputs: source code, existing documentation, design documents, user stories, API schemas (OpenAPI/Swagger), commit histories, or stakeholder interviews. Identify the authoritative source for each piece of information to ensure accuracy. Note any gaps that need clarification.

3. Design the Document Structure Create an outline following the conventions of the document type. API references use a consistent per-endpoint template. Tutorials follow a step-by-step progression. Architecture docs follow a decision-record format (context, decision, consequences). Plan where code examples, tables, and callout boxes will appear.

4. Write the Content Draft the document using clear, direct language. Prefer active voice and short sentences. Lead each section with the most important information. Include complete, runnable code examples that readers can copy and execute. Use consistent terminology and define acronyms on first use. Format according to the chosen standard (Markdown, reStructuredText, AsciiDoc).

5. Add Navigation and Cross-References Insert a table of contents for long documents, anchor links between related sections, and links to prerequisite or follow-up documentation. Add "Next steps" sections at the end of tutorials.

6. Review for Accuracy and Completeness Verify all code examples compile or run correctly. Confirm API endpoint paths, parameters, and response schemas match the actual implementation. Check that every tutorial step produces the described result. No placeholder text or TODO items should remain.

Usage

Provide the agent with:

• Document type — API reference, tutorial, user guide, changelog, architecture decision record, README
• Subject — the feature, API, tool, or system to document
• Audience — skill level and role of the intended readers
• Source material — code files, schemas, design docs, or a description of the feature
• Format — Markdown, reStructuredText, AsciiDoc, or HTML

Example prompt: "Write an API reference for the /users endpoint. The audience is third-party developers. Here is the OpenAPI spec: [attached file]."

Examples

Example 1: API Endpoint Reference

Input: "Document the POST /api/v1/webhooks endpoint. Creates a webhook subscription. Requires Bearer token auth. Body: url (string, required), events (string[], required), secret (string, optional). Returns 201 or 422."

Output:

POST /api/v1/webhooks

Creates a new webhook subscription. Requires a Bearer token in the Authorization header.

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint URL to receive payloads.
events	string[]	Yes	Event types to subscribe to (e.g., ["order.created"]).
secret	string	No	HMAC-SHA256 signing secret. Auto-generated if omitted.

curl -X POST https://api.example.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myapp.com/hooks","events":["order.created"]}'

201 Created: {"id":"wh_9a8b7c6d","url":"https://myapp.com/hooks","events":["order.created"],"active":true}

422 Error: {"error":{"code":"validation_error","details":[{"field":"url","message":"URL must use HTTPS."}]}}