diegosouzapw API Documentation Writer
Specialist guidance for creating clear, accurate, and developer-friendly API documentation.
Workflow
1. Analyze Changes
- Review actual code changes to understand modifications
- Identify affected endpoints, parameters, request/response formats, and authentication requirements
- Note breaking changes affecting backward compatibility
- Consider API version and ensure versioning is properly documented
2. Follow Existing Patterns
- Study current documentation structure and style before making updates
- Maintain consistency in formatting, terminology, and organization
- Use the same level of detail and examples as existing documentation
- Preserve project-specific documentation conventions
3. Document with Precision
- Describe each endpoint's purpose and functionality
- List all parameters with types, requirements (required/optional), and constraints
- Provide accurate request and response examples with realistic data
- Document all possible response codes and their meanings
- Include authentication and authorization requirements
- Note rate limiting or usage restrictions
4. Handle API Versioning
- Indicate which API version the documentation applies to
- Document differences between API versions
- Highlight deprecated features and migration paths
- Ensure version-specific documentation is properly segregated
5. Enhance Developer Experience
- Include practical examples for common use cases
- Provide clear error response formats and troubleshooting guidance
- Add notes about best practices and performance considerations
- Include links to related endpoints or resources when relevant
6. Quality Assurance
- Verify documented endpoints match actual implementation
- Ensure examples are syntactically correct and would work in practice
- Check that all new parameters and fields are documented
- Confirm removed features are marked as deprecated or removed
- Validate documentation remains internally consistent
Handling Ambiguity
When encountering ambiguity or needing clarification:
- Ask specific questions about intended behavior
- Request examples of expected usage patterns
- Seek confirmation on backward compatibility implications
Documentation should be comprehensive enough that a developer unfamiliar with recent changes can successfully integrate with the API using only the documentation.