4 min read • Guide 395 of 877
How to Manage Technical Documentation for APIs?
How to manage technical documentation for APIs?
Manage API documentation by including doc updates in API task definitions of done, storing documentation drafts in NoteVault during development, versioning docs with API releases, and creating separate doc review tasks. Use labels to identify tasks affecting public APIs that require documentation updates.
API documentation labels
| Label | Purpose |
|---|---|
| api:public | Public API - docs required |
| api:internal | Internal API |
| docs:required | Documentation update needed |
| docs:breaking | Breaking change - needs attention |
| docs:example | Example code update |
| docs:generated | Auto-generated docs |
API task with documentation
## API: Add User Preferences Endpoint
### Endpoint Design
- GET /api/v1/users/{id}/preferences
- PUT /api/v1/users/{id}/preferences
### Development
- [ ] Implement endpoints
- [ ] Add tests
- [ ] Code review
### Documentation (Required for public API)
- [ ] OpenAPI spec updated
- [ ] Request/response examples
- [ ] Error codes documented
- [ ] Authentication requirements
- [ ] Rate limits noted
- [ ] Changelog entry
Definition of Done:
- [ ] Docs reviewed by tech writer
- [ ] Examples tested and working
API documentation workflow:
- API design - Spec in NoteVault before coding
- Development - Build endpoint
- Draft docs - Update OpenAPI/docs during dev
- Code review - Include doc changes in PR
- Doc review - Tech writer or peer review
- Integration - Merge code + docs together
- Publish - Update public documentation
- Announce - Changelog, developer notification
NoteVault API documentation
# API Documentation
## Endpoints Overview
### Users API
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/v1/users | List users |
| GET | /api/v1/users/{id} | Get user |
| POST | /api/v1/users | Create user |
| PUT | /api/v1/users/{id} | Update user |
## Authentication
All endpoints require Bearer token authentication.
## Rate Limits
- Standard: 100 requests/minute
- Premium: 1000 requests/minute
## Error Codes
| Code | Message | Resolution |
|------|---------|------------|
| 401 | Unauthorized | Check API key |
| 429 | Rate limited | Wait and retry |
| 500 | Server error | Contact support |
## Versioning
- Current: v1
- Deprecated: none
- Breaking changes: 90-day notice
## Changelog
### 2025-01-27 - v1.5.0
- Added: User preferences endpoints
- Changed: Rate limits increased
- Deprecated: None
Documentation quality checklist
- [ ] All endpoints documented
- [ ] Request/response examples included
- [ ] Examples are tested and working
- [ ] Error codes explained
- [ ] Authentication described
- [ ] Rate limits documented
- [ ] Versioning clear
- [ ] Changelog updated