Managing Service Documentation
1. Documenting REST APIs
| Element | Detail |
|---|---|
| OpenAPI 3.1 | Machine-readable spec |
| Examples | Per operation; req + resp |
| Errors | RFC 9457 schema |
| UI | Swagger UI / Redoc / Stoplight |
2. Documenting GraphQL APIs
| Element | Detail |
|---|---|
| SDL comments | Schema as docs |
| Introspection | Powers explorers |
| Tools | GraphiQL, Apollo Studio, GraphQL Voyager |
3. Documenting gRPC APIs
| Element | Detail |
|---|---|
| .proto comments | Source of truth |
| Generators | protoc-gen-doc, Buf |
| Buf Schema Registry | Versioned schemas |
4. Creating Architecture Diagrams
| Notation | Detail |
|---|---|
| C4 | Context → Container → Component → Code |
| Diagrams-as-code | Mermaid, PlantUML, Structurizr, D2 |
| Live | Auto-render from traces / mesh |
5. Documenting Service Contracts
| Type | Detail |
|---|---|
| API contract | OpenAPI / proto |
| Event contract | AsyncAPI / Avro / proto |
| SLA | Latency, availability targets |
6. Maintaining API Changelog
| Section | Detail |
|---|---|
| Added | New endpoints/fields |
| Changed | Behavior changes |
| Deprecated | Sunset date |
| Removed | Breaking |
| Fixed | Bug fixes |
7. Documenting Configuration
| Element | Detail |
|---|---|
| Each var | Name, default, range, owner |
| Per env | dev / stage / prod |
| Secrets | Reference, not value |
8. Creating Runbooks
| Section | Detail |
|---|---|
| Symptoms | What you see |
| Diagnosis | Queries, dashboards |
| Mitigation | Step-by-step |
| Escalation | Who to page |
| Link from alert | Direct URL in payload |
9. Documenting Error Codes
| Field | Example |
|---|---|
| Code | ORDER_OUT_OF_STOCK |
| HTTP | 409 |
| Cause | Inventory below requested qty |
| Remedy | Reduce qty or wait restock |
10. Maintaining Developer Guides
| Doc | Detail |
|---|---|
| Quickstart | 5-min hello world |
| How-to | Task-oriented |
| Reference | Generated from spec |
| Concepts | Mental model |
| Framework | Diátaxis |
11. Using API Documentation Tools
| Tool | Use |
|---|---|
| Swagger UI / Redoc | OpenAPI |
| Stoplight | Design + docs |
| Mintlify / Bump.sh / ReadMe | Hosted |
| Backstage TechDocs | Markdown next to code |
12. Implementing Interactive Documentation
| Feature | Detail |
|---|---|
| Try-it console | Real calls from docs |
| Code samples | Auto-generated per language |
| Auth widget | Bearer token in browser |
| SDK download | Generated from spec |