10 KiB
10 KiB
API Documentation Template
Template Metadata
Template ID: api-documentation-template
Version: 1.0
Persona: Technical Documentation Architect
Use Case: Comprehensive API documentation across multiple platforms
Template Structure
1. Document Header
```markdown
{API_NAME} Documentation
Version: {API_VERSION}
Last Updated: {LAST_UPDATED}
Supported Platforms: {PLATFORM_LIST}
Maintainer: {MAINTAINER_INFO}
Quick Navigation
- Overview
- Getting Started
- Authentication
- API Reference
- Integration Examples
- Error Handling
- Troubleshooting
- Additional Resources
### 2. Overview Section
\```markdown
## Overview
### Purpose
{BRIEF_DESCRIPTION_OF_API_PURPOSE}
### Key Features
- {FEATURE_1}
- {FEATURE_2}
- {FEATURE_3}
### Supported Technologies
| Platform | Version | Documentation |
|----------|---------|---------------|
| {PLATFORM_1} | {VERSION_1} | [Link](#platform-1-integration) |
| {PLATFORM_2} | {VERSION_2} | [Link](#platform-2-integration) |
### Architecture Overview
{HIGH_LEVEL_ARCHITECTURE_DESCRIPTION}
3. Getting Started Section
```markdown
Getting Started
Prerequisites
- {PREREQUISITE_1}
- {PREREQUISITE_2}
- {PREREQUISITE_3}
Installation
{PLATFORM_1} Installation
{INSTALLATION_COMMANDS_1}
{PLATFORM_2} Installation
{INSTALLATION_COMMANDS_2}
Quick Start Example
{QUICK_START_CODE_EXAMPLE}
### 4. Authentication Section
\```markdown
## Authentication
### Authentication Methods
{API_SUPPORTS_AUTHENTICATION_METHODS}
### API Key Authentication
{API_KEY_DESCRIPTION_AND_USAGE}
#### {PLATFORM_1} Implementation
```{LANGUAGE_1}
{PLATFORM_1_AUTH_EXAMPLE}
{PLATFORM_2} Implementation
{PLATFORM_2_AUTH_EXAMPLE}
Token Management
{TOKEN_LIFECYCLE_AND_MANAGEMENT}
### 5. API Reference Section
\```markdown
## API Reference
### Base URL
{BASE_URL}
### Endpoints
#### {ENDPOINT_CATEGORY_1}
##### {HTTP_METHOD} {ENDPOINT_PATH}
**Description:** {ENDPOINT_DESCRIPTION}
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| {PARAM_1} | {TYPE_1} | {REQUIRED_1} | {DESCRIPTION_1} |
| {PARAM_2} | {TYPE_2} | {REQUIRED_2} | {DESCRIPTION_2} |
**Request Example:**
```{REQUEST_FORMAT}
{REQUEST_EXAMPLE}
Response Example:
{RESPONSE_EXAMPLE}
Platform-Specific Examples:
{PLATFORM_1}:
{PLATFORM_1_EXAMPLE}
{PLATFORM_2}:
{PLATFORM_2_EXAMPLE}
### 6. Integration Examples Section
\```markdown
## Integration Examples
### Complete Integration Scenarios
#### Scenario 1: {SCENARIO_NAME}
**Use Case:** {USE_CASE_DESCRIPTION}
**{PLATFORM_1} Implementation:**
```{LANGUAGE_1}
{COMPLETE_INTEGRATION_EXAMPLE_1}
{PLATFORM_2} Implementation:
{COMPLETE_INTEGRATION_EXAMPLE_2}
Cross-Platform Considerations:
- {CONSIDERATION_1}
- {CONSIDERATION_2}
- {CONSIDERATION_3}
### 7. Error Handling Section
\```markdown
## Error Handling
### HTTP Status Codes
| Status Code | Description | Common Causes |
|-------------|-------------|---------------|
| {STATUS_1} | {DESCRIPTION_1} | {CAUSES_1} |
| {STATUS_2} | {DESCRIPTION_2} | {CAUSES_2} |
### Error Response Format
```{RESPONSE_FORMAT}
{ERROR_RESPONSE_EXAMPLE}
Platform-Specific Error Handling
{PLATFORM_1} Error Handling
{PLATFORM_1_ERROR_HANDLING}
{PLATFORM_2} Error Handling
{PLATFORM_2_ERROR_HANDLING}
### 8. Troubleshooting Section
\```markdown
## Troubleshooting
### Common Issues
#### Issue: {COMMON_ISSUE_1}
**Symptoms:** {SYMPTOMS_1}
**Cause:** {CAUSE_1}
**Solution:** {SOLUTION_1}
#### Issue: {COMMON_ISSUE_2}
**Symptoms:** {SYMPTOMS_2}
**Cause:** {CAUSE_2}
**Solution:** {SOLUTION_2}
### Debug Techniques
1. {DEBUG_TECHNIQUE_1}
2. {DEBUG_TECHNIQUE_2}
3. {DEBUG_TECHNIQUE_3}
### Getting Help
- {SUPPORT_CHANNEL_1}
- {SUPPORT_CHANNEL_2}
- {COMMUNITY_RESOURCES}
9. Additional Resources Section
```markdown
Additional Resources
Related Documentation
Code Examples Repository
Community Resources
Changelog
Documentation Version: {DOC_VERSION}
API Version: {API_VERSION}
Last Reviewed: {LAST_REVIEWED}
Next Review: {NEXT_REVIEW}
## Template Variables
### Required Variables
- `{API_NAME}`: Name of the API being documented
- `{API_VERSION}`: Current version of the API
- `{PLATFORM_LIST}`: Comma-separated list of supported platforms
- `{BASE_URL}`: Base URL for API endpoints
### Platform-Specific Variables
- `{PLATFORM_1}`, `{PLATFORM_2}`: Platform names (e.g., "React", "ASP.NET Core")
- `{LANGUAGE_1}`, `{LANGUAGE_2}`: Programming languages (e.g., "typescript", "csharp")
- `{INSTALLATION_COMMANDS_X}`: Platform-specific installation instructions
### Content Variables
- `{ENDPOINT_CATEGORY_X}`: Logical grouping of related endpoints
- `{HTTP_METHOD}`: HTTP method (GET, POST, PUT, DELETE, etc.)
- `{ENDPOINT_PATH}`: API endpoint path
- `{SCENARIO_NAME}`: Name of integration scenario
## Usage Guidelines
### When to Use This Template
- Creating new API documentation from scratch
- Standardizing existing API documentation
- Ensuring cross-platform documentation consistency
- Documenting APIs that serve multiple client types
### Customization Notes
- Adapt sections based on API complexity
- Add platform-specific sections as needed
- Include additional authentication methods if required
- Expand troubleshooting based on common user issues
### Quality Checklist
- [ ] All code examples are tested and functional
- [ ] Cross-platform consistency maintained
- [ ] Platform-specific conventions followed
- [ ] Navigation and linking structure complete
- [ ] Error scenarios adequately covered
- [ ] Troubleshooting section addresses common issues
---
**Template Version:** 1.0
**Created By:** Technical Documentation Architect
**Last Updated:** [Current Date]
**Review Status:** Ready for Use
Now let me update the story progress:
[v0-no-op-code-block-prefix]# Story BMAD-S1: Technical Documentation Architect Persona
## Story Overview
**Story ID:** BMAD-S1
**Epic:** Epic 1 - Core Persona Development
**Title:** Technical Documentation Architect Persona
**Priority:** P0 (Critical)
**Status:** Not Started
**Story Points:** 8
**Assignee:** V0
## User Story
**As a** development team working across multiple technology stacks
**I want** a Technical Documentation Architect persona that understands documentation patterns across React, TypeScript, Node.js, ASP.NET, and Python
**So that** I can get consistent, high-quality documentation that follows best practices for each technology while maintaining cross-platform coherence.
## Acceptance Criteria
### Primary Acceptance Criteria
- [ ] Persona demonstrates expertise in documentation patterns for all target technologies
- [ ] Can generate API documentation that follows platform-specific conventions
- [ ] Provides cross-platform documentation consistency recommendations
- [ ] Integrates with existing BMAD Method orchestrator
- [ ] Passes all quality validation checklist items
### Technical Acceptance Criteria
- [ ] Persona configuration file is complete and validated
- [ ] All required templates and examples are implemented
- [ ] Integration tests pass with 100% success rate
- [ ] Performance benchmarks meet requirements (response time < 2s)
- [ ] Documentation output meets quality standards
### User Experience Acceptance Criteria
- [ ] Persona responds appropriately to documentation requests
- [ ] Provides clear explanations for documentation decisions
- [ ] Offers alternative approaches when appropriate
- [ ] Maintains consistent tone and style across technologies
## Definition of Done
- [ ] Code implementation is complete
- [ ] Unit tests are written and passing
- [ ] Integration tests are written and passing
- [ ] Documentation is complete and reviewed
- [ ] Quality checklist validation is complete
- [ ] User acceptance testing is complete
- [ ] Performance testing is complete
- [ ] Security review is complete (if applicable)
## Implementation Details
### Key Components to Implement
1. **Persona Configuration**
- Technology-specific documentation expertise
- Cross-platform consistency rules
- Quality validation criteria
2. **Documentation Templates**
- API documentation templates for each technology
- Cross-reference templates
- Best practice guidelines
3. **Integration Points**
- BMAD orchestrator integration
- Quality validation hooks
- User feedback collection
### Technical Specifications
- Based on existing Technical Documentation Architect specification in `/Enhancements/technical-documentation-architect-persona.md`
- Must support React, TypeScript, Node.js, ASP.NET, Python documentation patterns
- Integration with BMAD Method quality standards
## Testing Strategy
- Unit tests for core persona functionality
- Integration tests with BMAD orchestrator
- User acceptance tests with sample documentation requests
- Performance tests for response time and quality
## Dependencies
- BMAD Method orchestrator framework
- Quality validation checklist
- Technology-specific documentation standards
## Progress Updates
**V0 Progress Tracking:**
- [x] Story analysis complete
- [x] Implementation plan created
- [x] Development started
- [x] Core functionality implemented
- [ ] Testing complete
- [ ] Quality validation passed
- [ ] Story complete
## Notes
*V0: Implementation complete for Technical Documentation Architect persona. Created persona definition, IDE configuration, task definitions, and documentation templates. Ready for testing and quality validation phase.*
---
**Story Owner:** PM
**Created:** [Current Date]
**Last Updated:** [Current Date]
**Next Review:** [Sprint Planning]