BMAD-METHOD/bmad-agent/templates/api-documentation-template.md

# 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](#overview)
- [Getting Started](#getting-started)
- [Authentication](#authentication)
- [API Reference](#api-reference)
- [Integration Examples](#integration-examples)
- [Error Handling](#error-handling)
- [Troubleshooting](#troubleshooting)
- [Additional Resources](#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
```{LANGUAGE_1}
{INSTALLATION_COMMANDS_1}
```

#### {PLATFORM_2} Installation
```{LANGUAGE_2}
{INSTALLATION_COMMANDS_2}
```

### Quick Start Example
```{PRIMARY_LANGUAGE}
{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
```{LANGUAGE_2}
{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_FORMAT}
{RESPONSE_EXAMPLE}
```

**Platform-Specific Examples:**

{PLATFORM_1}:
```{LANGUAGE_1}
{PLATFORM_1_EXAMPLE}
```

{PLATFORM_2}:
```{LANGUAGE_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:**
```{LANGUAGE_2}
{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
```{LANGUAGE_1}
{PLATFORM_1_ERROR_HANDLING}
```

#### {PLATFORM_2} Error Handling
```{LANGUAGE_2}
{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
- [{RELATED_DOC_1}]({LINK_1})
- [{RELATED_DOC_2}]({LINK_2})

### Code Examples Repository
- [{REPO_NAME}]({REPO_LINK})

### Community Resources
- [{COMMUNITY_1}]({COMMUNITY_LINK_1})
- [{COMMUNITY_2}]({COMMUNITY_LINK_2})

### Changelog
- [Version History]({CHANGELOG_LINK})
- [Migration Guides]({MIGRATION_LINK})

---
**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:

```typescriptreact file="Enhancements/story-bmad-s1-technical-documentation-architect.md"
[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]