ometere123/the-skills-bible/api-documentation-engineer

API Documentation Engineer

Purpose

Build and operate documentation that lets independent consumers understand and use the real interface safely.

Use this skill when

• Create accurate reference, task guides, examples, concepts, errors, limits, changelogs, and migration documentation from verified contracts.
• Independent producers and consumers need an explicit, supported contract.
• Interface behaviour must remain reliable across versions, failures, and organisational boundaries.
• Developer experience and operational evidence are part of the delivery outcome.

Do not use this skill as the primary workflow when

• The work is entirely internal to one module with no independent consumer contract.
• A previously defined generic architecture or security workflow is the dominant task.
• The requested change cannot be authorised, observed, or supported through its lifecycle.

Required inputs

• Consumer workflows, constraints, and expected outcomes.
• Current specifications, schemas, examples, SDKs, and implementation behaviour.
• Identity, tenant, data, permission, and secret requirements.
• Workload, payload, latency, quota, and dependency limits.
• Supported versions, release policy, incidents, and consumer inventory.

Classify missing information as blocking, important, or optional. Inspect the actual specifications, code, gateway policies, SDKs, credentials, usage, delivery evidence, and support history before asking for information that can be verified directly.

Core operating principles

• Design interfaces around stable consumer outcomes rather than internal implementation structure.
• Treat schemas, examples, documentation, SDKs, policies, and compatibility rules as versioned production artefacts.
• Prefer explicit contracts, deterministic validation, idempotent effects, and bounded failure semantics.
• Keep identity, tenant, permission, quota, and ownership decisions authoritative and server-enforced.
• Preserve backward compatibility deliberately and make breaking changes visible, testable, and migratable.
• Design retries, timeouts, cancellation, pagination, ordering, and partial failure as part of the public contract.
• Protect consumers from implementation churn while avoiding abstractions that hide important differences.
• Make integrations observable end to end through stable identifiers, correlation, delivery state, and reconciliation.
• Provide realistic examples, sandboxes, diagnostics, and migration guidance so consumers can succeed independently.
• Govern the full lifecycle from discovery and onboarding through change, deprecation, offboarding, and retirement.

Workflow

1. Define the consumer outcome

• State the required outcome for documentation that lets independent consumers understand and use the real interface safely.
• Identify unacceptable ambiguity, side effects, and consumer failure.

2. Map actors and trust boundaries

• Map new developers, experienced integrators, SDK users, partner teams, support, and API producers.
• Assign provider, consumer, platform, security, support, and decision ownership.

3. Define the public contract

• Specify operations, schemas, fields, examples, authentication, errors, pagination, quotas, webhooks, and lifecycle states.
• Separate public semantics from internal implementation and document authoritative behaviour.

4. Secure identity and data

• Design credential handling, sensitive examples, permission requirements, callback safety, privacy, and safe troubleshooting.
• Validate every trust decision at the authoritative boundary and minimise exposed data.

5. Engineer reliability

• Define retry guidance, idempotency, timeout, partial failure, operation status, support identifiers, and recovery.
• Make partial success, unknown outcomes, cancellation, and recovery visible to consumers.

6. Bound scalability and cost

• Control payload limits, rate limits, pagination, batching, concurrency, data volume, and performance expectations.
• Set explicit limits, fair-use rules, capacity assumptions, and dependency protections.

7. Design developer experience

• Provide quick starts, task guides, reference, recipes, copyable examples, diagrams, troubleshooting, and changelogs.
• Ensure a new consumer can complete the critical workflow without undocumented support knowledge.

8. Validate compatibility

• Test versioned documentation, example tests, SDK matrices, deprecated features, migration guides, and archived versions.
• Use supported consumers, generated clients, contract fixtures, and mixed-version scenarios.

9. Instrument operations

• Observe page usage, search gaps, failed examples, support topics, outdated pages, version selection, and migration progress.
• Correlate consumer-visible failures with provider, dependency, contract, and release evidence.

10. Govern the lifecycle

• Define publication, ownership, support, change review, deprecation, offboarding, and retirement.
• Record residual risks, exceptions, migration deadlines, and review triggers.

Decision rules

Required outputs

• Consumer outcome and scope.
• Actor, ownership, and trust map.
• Versioned interface or integration contract.
• Identity, permission, and data controls.
• Reliability and recovery semantics.
• Limits, capacity, and fairness policy.
• Developer onboarding and diagnostic assets.
• Compatibility and migration evidence.
• Operational telemetry and support model.
• Lifecycle, exception, and retirement record.

API, SDK, and integration quality gates

• Consumer gate: Target consumers, workflows, constraints, and success outcomes are explicit.
• Contract gate: Inputs, outputs, errors, state changes, ordering, retries, and limits are precise.
• Identity gate: Authentication, authorisation, tenant, delegation, and credential lifecycle are enforced.
• Compatibility gate: Supported versions, additive changes, breaking changes, and migration paths are documented and tested.
• Reliability gate: Timeouts, idempotency, retries, partial failure, reconciliation, and degraded behaviour are operational.
• Security gate: Untrusted inputs, callbacks, secrets, permissions, and third-party data are bounded.
• Developer gate: Documentation, examples, diagnostics, sandbox behaviour, and SDK ergonomics support independent adoption.
• Observability gate: Requests, deliveries, retries, transformations, failures, and partner outcomes are traceable.
• Scalability gate: Quotas, pagination, payload limits, batching, concurrency, and dependency ceilings are explicit.
• Lifecycle gate: Onboarding, change, deprecation, offboarding, data deletion, and retirement have accountable owners.

Evidence standard

For consequential conclusions, identify the exact API or protocol version, schema, SDK version, environment, consumer, identity, tenant, payload, dependency state, request or delivery identifier, and time window. Distinguish observed contract behaviour, supported inference, and undocumented assumptions. Do not claim compatibility from schema comparison alone when semantics or side effects differ.

Failure handling and escalation

Pause or escalate when:

• The authoritative contract, owner, or consumer expectation is unclear.
• Credentials, tenant boundaries, permissions, callback destinations, or data rights cannot be verified.
• Retrying may duplicate money movement, messages, records, or other external side effects.
• A breaking change affects unknown or uncontactable consumers.
• Third-party behaviour conflicts with documented guarantees or creates active data loss.
• Production testing could send real communications, incur charges, or affect external users.
• Residual integration, security, privacy, or operational risk exceeds delegated authority.

Report the exact blocker, verified state, affected consumers, evidence, safe options, and smallest required decision.

Common anti-patterns

• Reference generated without task guidance.
• Examples that are never executed.
• Documentation describing intended rather than actual behaviour.
• Using real secrets or personal data.
• Limits hidden in support articles.
• Changelog without migration actions.

Completion checklist

• [ ] Consumer outcomes and exclusions are explicit.
• [ ] Provider and consumer ownership is recorded.
• [ ] The contract includes failure and side-effect semantics.
• [ ] Identity, tenant, and data boundaries are enforced.
• [ ] Retries, timeouts, and unknown outcomes are safe.
• [ ] Limits and dependency ceilings are explicit.
• [ ] Independent consumers can integrate from published assets.
• [ ] Supported versions pass compatibility tests.
• [ ] Operations can correlate and reconcile failures.
• [ ] Deprecation and retirement are executable.

Interface and integration record

# Interface and Integration Record
 
## Outcome
[Consumer workflow, partner exchange, SDK use case, or integration result]
 
## Scope
[Providers, consumers, environments, identities, tenants, data, and exclusions]
 
## Contract
[Operations, schemas, errors, ordering, pagination, quotas, and side effects]
 
## Compatibility
[Versions, supported clients, additive rules, breaking changes, and migration]
 
## Reliability
[Timeouts, retries, idempotency, delivery, reconciliation, and recovery]
 
## Security and privacy
[Credentials, permissions, validation, secrets, callbacks, and data lifecycle]
 
## Developer experience
[Documentation, examples, SDKs, sandbox, diagnostics, and support]
 
## Observability
[Identifiers, traces, logs, metrics, dashboards, and partner evidence]
 
## Residual risk
[Known limitations, owner, acceptance, expiry, and communication]
 
## Lifecycle
[Rollout, deprecation, offboarding, deletion, and retirement]

Related skills

• developer-portal-engineer
• api-sandbox-mock-engineer
• sdk-developer-experience-engineer
• api-versioning-compatibility-engineer

Maintenance rules

Review this skill when consumers, schemas, protocols, providers, SDKs, limits, regulations, or operational dependencies change; incidents reveal missing contract behaviour; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable schemas, examples, validators, fixtures, or compatibility tests would improve execution.