From 987cb4e54d45174412ace45e1f03685cc23be71c Mon Sep 17 00:00:00 2001 From: jalagon Date: Tue, 19 Aug 2025 21:09:20 +0200 Subject: [PATCH] Add document feature commands and documentation --- document_feature.md | 279 +++++++++++++++++++++++ document_feature_advanced.md | 415 +++++++++++++++++++++++++++++++++++ 2 files changed, 694 insertions(+) create mode 100644 document_feature.md create mode 100644 document_feature_advanced.md diff --git a/document_feature.md b/document_feature.md new file mode 100644 index 0000000..04baa56 --- /dev/null +++ b/document_feature.md @@ -0,0 +1,279 @@ +# Document Feature Command + +Generate comprehensive documentation for a new feature, creating both developer and user-facing guides. + +## Usage +```bash +claude document-feature [feature-name] [options] +``` + +## Options +- `--type`: Specify feature type (frontend|backend|fullstack) - auto-detected if not provided +- `--user-role`: Target user role for user docs (admin|user|developer) - defaults to 'user' +- `--include-api`: Include API documentation (default: true for backend/fullstack) +- `--screenshot-mode`: How to handle screenshots (placeholder|capture|skip) - defaults to 'placeholder' + +## Command Implementation + +You are an expert technical writer and documentation specialist. Your task is to analyze a feature implementation and generate comprehensive, dual-purpose documentation. + +### Step 1: Feature Analysis +First, analyze the codebase to understand the feature: + +1. **Identify feature scope and type:** + - Search for files related to `{{feature-name}}` + - Determine if it's frontend, backend, or full-stack + - Identify key components, APIs, database changes, and UI elements + - Find related configuration files, tests, and dependencies + +2. **Analyze existing documentation patterns:** + - Check `docs/` directory structure and naming conventions + - Review existing documentation files for style and format + - Identify common sections and templates used in the project + +3. **Map user interactions:** + - Identify user-facing features and workflows + - Determine required user permissions or roles + - Map the complete user journey for this feature + +### Step 2: Generate Developer Documentation + +Create `docs/dev/{{feature-name}}-implementation.md` with: + +```markdown +# {{Feature Name}} - Developer Documentation + +## Overview +Brief technical overview of what this feature does and why it was implemented. + +## Architecture +- **Type**: [Frontend/Backend/Full-stack] +- **Components**: List key components/modules +- **Dependencies**: New dependencies added +- **Database Changes**: Schema modifications if any + +## Implementation Details + +### Backend Implementation +[If applicable] +- API endpoints and methods +- Database models and relationships +- Business logic and services +- Authentication/authorization requirements + +### Frontend Implementation +[If applicable] +- Components and their hierarchy +- State management approach +- Routing changes +- UI/UX considerations + +### Configuration +- Environment variables +- Feature flags +- Configuration files modified + +## API Reference +[If applicable] +### Endpoints +- `GET /api/{{feature-name}}` - Description +- `POST /api/{{feature-name}}` - Description +[Include request/response examples] + +## Testing +- Unit tests: `{{test-file-paths}}` +- Integration tests: `{{test-file-paths}}` +- E2E tests: `{{test-file-paths}}` + +## Security Considerations +- Authentication requirements +- Authorization levels +- Data validation +- Potential security implications + +## Performance Impact +- Database query impact +- Caching considerations +- Resource usage + +## Deployment Notes +- Migration requirements +- Environment-specific configurations +- Rollback procedures + +## Related Documentation +- [User Guide](../user/{{feature-name}}-guide.md) +- [API Documentation](./api-reference.md) +- [Related Feature Docs] + +## Troubleshooting +Common issues and their solutions. + +--- +*Generated on {{current-date}} | Last updated: {{current-date}}* +``` + +### Step 3: Generate User Documentation + +Create `docs/user/{{feature-name}}-guide.md` with: + +```markdown +# How to Use {{Feature Name}} + +## What is {{Feature Name}}? +Simple explanation of what the feature does and why users would want to use it. + +## Who Can Use This Feature? +- User roles that have access +- Required permissions + +## Getting Started + +### Prerequisites +What users need before they can use this feature. + +### Quick Start +1. **Access the feature** + ![Screenshot: Navigation to feature](screenshots/{{feature-name}}-navigation.png) + +2. **Basic setup** (if required) + ![Screenshot: Initial setup](screenshots/{{feature-name}}-setup.png) + +## Step-by-Step Guide + +### Task 1: [Primary Use Case] +1. **Step 1 description** + ![Screenshot: Step 1](screenshots/{{feature-name}}-step1.png) + +2. **Step 2 description** + ![Screenshot: Step 2](screenshots/{{feature-name}}-step2.png) + +### Task 2: [Secondary Use Case] +[Similar structure] + +## Tips and Best Practices +- Helpful tips for effective use +- Common workflows +- Time-saving shortcuts + +## Troubleshooting + +### Common Issues +**Problem**: Issue description +**Solution**: How to fix it + +**Problem**: Another issue +**Solution**: How to fix it + +### Getting Help +- Where to find additional support +- How to report bugs or request features + +## Related Features +- Links to related user guides +- Features that work well together + +--- +*Need help? Contact [support link] | [Developer docs](../dev/{{feature-name}}-implementation.md)* +``` + +### Step 4: Screenshot Management + +Based on `--screenshot-mode`: + +**Placeholder mode (default):** +- Create placeholder references with descriptive names +- Generate a `docs/screenshots/{{feature-name}}/README.md` file listing all required screenshots + +**Capture mode (bonus):** +- Use automated screenshot capture tools +- Generate actual screenshot files in `docs/screenshots/{{feature-name}}/` + +**Skip mode:** +- Remove all screenshot references from user documentation + +### Step 5: Cross-Reference Generation + +1. **Update main documentation index:** + - Add entries to `docs/README.md` or main index + - Update feature matrix or capability table + +2. **Create cross-references:** + - Link user docs to developer docs and vice versa + - Update related feature documentation with references + - Add to search index if one exists + +3. **Generate navigation updates:** + - Update documentation sidebars/menus + - Add breadcrumb navigation + +### Step 6: Quality Assurance + +1. **Validate documentation:** + - Check for broken internal links + - Verify code examples compile/run + - Ensure consistent formatting and style + +2. **Generate documentation manifest:** + ```json + { + "feature": "{{feature-name}}", + "type": "{{detected-type}}", + "generated": "{{timestamp}}", + "files": [ + "docs/dev/{{feature-name}}-implementation.md", + "docs/user/{{feature-name}}-guide.md" + ], + "screenshots": ["list-of-screenshot-files"], + "cross_references": ["list-of-updated-files"] + } + ``` + +## Output Format + +After generation, provide a summary: + +``` +โœ… Documentation generated for: {{feature-name}} + +๐Ÿ“‹ Files created: +โ€ข docs/dev/{{feature-name}}-implementation.md ({{word-count}} words) +โ€ข docs/user/{{feature-name}}-guide.md ({{word-count}} words) + +๐Ÿ“ธ Screenshots needed: +โ€ข {{count}} placeholder screenshots created +โ€ข See docs/screenshots/{{feature-name}}/README.md for details + +๐Ÿ”— Cross-references updated: +โ€ข {{count}} related documents updated +โ€ข Navigation menus updated + +โšก Next steps: +1. Review and edit the generated documentation +2. Capture required screenshots +3. Test all links and code examples +4. Publish to documentation site +``` + +## Advanced Features + +### Feature Type Detection +Analyze the codebase to determine feature type: +- **Frontend**: Look for component files, stylesheets, client-side routing +- **Backend**: Look for API routes, database models, server-side logic +- **Full-stack**: Combination of both + +### Related Documentation Discovery +- Scan existing docs for related features +- Identify integration points +- Suggest additional cross-references + +### Template Customization +- Detect project-specific documentation templates +- Adapt generated docs to match existing style +- Include project-specific sections (e.g., accessibility notes, localization) + +### Continuous Integration +- Generate docs that can be validated in CI/CD +- Include metadata for automated testing +- Create documentation diff reports for reviews \ No newline at end of file diff --git a/document_feature_advanced.md b/document_feature_advanced.md new file mode 100644 index 0000000..97e07c8 --- /dev/null +++ b/document_feature_advanced.md @@ -0,0 +1,415 @@ +# Enhanced Documentation Generator v2.0 + +Generate intelligent, multi-dimensional documentation with AI-powered analysis, accessibility compliance, and automated quality assurance. + +## Usage +```bash +claude document-feature [feature-name] [options] +``` + +## Advanced Options +- `--languages`: Target languages (en|es|de|fr|auto) - defaults to 'auto' (detects from project) +- `--ai-analysis`: Deep code analysis level (basic|advanced|comprehensive) - defaults to 'advanced' +- `--accessibility`: Generate accessibility docs (true|false|audit) - defaults to 'true' +- `--design-system`: Integrate with design system (figma|storybook|custom|none) - auto-detected +- `--quality-target`: Documentation quality target (80|90|95) - defaults to '90' +- `--screenshot-ai`: AI screenshot generation (enabled|disabled|smart) - defaults to 'smart' +- `--version-tracking`: Enable version-aware docs (true|false) - defaults to 'true' +- `--integration`: Project management integration (jira|linear|github|notion|auto) - auto-detected + +## Command Implementation + +You are an expert AI documentation architect with deep expertise in modern development workflows, accessibility standards, and multilingual technical communication. + +### Phase 1: Intelligent Codebase Analysis + +#### ๐Ÿง  AI-Powered Code Understanding +```python +# Pseudo-code for AI analysis engine +def analyze_feature_with_ai(feature_name, analysis_level): + """ + Use advanced code analysis to understand feature architecture, + dependencies, and user impact at a deeper level than traditional parsing. + """ + + # 1. Semantic Code Analysis + code_graph = build_semantic_dependency_graph(feature_name) + business_logic = extract_business_rules_and_logic(code_graph) + user_impact_areas = identify_user_facing_changes(code_graph) + + # 2. Architecture Pattern Detection + patterns = detect_architectural_patterns(code_graph) + anti_patterns = identify_potential_issues(code_graph) + complexity_metrics = calculate_cognitive_complexity(code_graph) + + # 3. Integration Impact Analysis + upstream_effects = analyze_upstream_dependencies(code_graph) + downstream_effects = analyze_downstream_impacts(code_graph) + breaking_changes = detect_potential_breaking_changes(code_graph) + + # 4. Security & Performance Implications + security_surface = analyze_security_implications(code_graph) + performance_impact = predict_performance_characteristics(code_graph) + + return FeatureAnalysis( + complexity=complexity_metrics, + patterns=patterns, + user_journeys=user_impact_areas, + security_notes=security_surface, + performance_profile=performance_impact + ) +``` + +#### ๐ŸŒ Multi-Language Project Detection +```yaml +# Auto-detect project internationalization setup +project_languages: + detection_sources: + - package.json (i18next, react-intl, vue-i18n) + - locale files (en.json, es.json, de.json, fr.json) + - framework config (nuxt.config.js, next.config.js) + - backend i18n (Django, Rails, Spring Boot) + + fallback_strategy: + - Analyze commit messages for language patterns + - Check team member locations (git blame analysis) + - Default to en|es|de based on user preference +``` + +### Phase 2: Intelligent Documentation Generation + +#### ๐Ÿ“š Adaptive Template Engine +```markdown +# The system adapts to your existing patterns and creates documentation that feels native + +## Auto-Detected Documentation Patterns: +- **Style Guide**: {{detected_style}} (Gitbook|Notion|Docusaurus|Custom) +- **Tone**: {{detected_tone}} (Technical|Conversational|Formal|Mixed) +- **Structure**: {{detected_structure}} (Task-based|Reference|Tutorial|Hybrid) +- **Code Examples**: {{code_style}} (Minimal|Verbose|Interactive|Annotated) + +## Generated Documentation Architecture: + +### ๐ŸŽฏ Developer Documentation (Multi-Dimensional) +`docs/dev/{{feature-name}}/` +โ”œโ”€โ”€ `implementation.md` - Core technical documentation +โ”œโ”€โ”€ `architecture.md` - System design and patterns +โ”œโ”€โ”€ `api-reference.md` - Complete API documentation with examples +โ”œโ”€โ”€ `testing-guide.md` - Comprehensive testing strategy +โ”œโ”€โ”€ `deployment.md` - Deployment and operations guide +โ”œโ”€โ”€ `accessibility.md` - Accessibility implementation notes +โ”œโ”€โ”€ `i18n.md` - Internationalization guidelines +โ””โ”€โ”€ `troubleshooting.md` - Advanced debugging guide + +### ๐Ÿ‘ฅ User Documentation (Experience-Focused) +`docs/user/{{feature-name}}/` +โ”œโ”€โ”€ `{{lang}}/` - Language-specific user guides +โ”‚ โ”œโ”€โ”€ `getting-started.md` - Quick start guide +โ”‚ โ”œโ”€โ”€ `user-guide.md` - Complete user manual +โ”‚ โ”œโ”€โ”€ `accessibility.md` - Accessibility user guide +โ”‚ โ””โ”€โ”€ `troubleshooting.md` - User-friendly troubleshooting +โ”œโ”€โ”€ `screenshots/` - AI-generated and annotated screenshots +โ”œโ”€โ”€ `videos/` - Placeholder for walkthrough videos +โ””โ”€โ”€ `accessibility-audit.md` - WCAG compliance report +``` + +#### ๐ŸŽจ Design System Integration +```javascript +// Auto-detect and integrate with existing design systems +const designSystemIntegration = { + figma: { + detect: () => checkForFigmaTokens() || checkFigmaAPI(), + extract: () => extractComponentSpecs(), + document: () => generateComponentDocs() + }, + + storybook: { + detect: () => checkStorybookConfig(), + extract: () => parseStoryFiles(), + document: () => generateInteractiveExamples() + }, + + custom: { + detect: () => findDesignTokens() || findStyleGuide(), + extract: () => parseCustomSystem(), + document: () => generateSystemDocs() + } +} +``` + +### Phase 3: AI-Enhanced Content Generation + +#### ๐Ÿ” Smart Screenshot Generation +```python +def generate_intelligent_screenshots(feature_name, user_journey): + """ + AI-powered screenshot generation with automatic annotation + """ + + # 1. Journey Mapping + user_flows = map_critical_user_journeys(feature_name) + screenshot_points = identify_screenshot_opportunities(user_flows) + + # 2. Automated Capture + for point in screenshot_points: + screenshot = capture_screen_at_state(point.app_state) + annotations = generate_smart_annotations(screenshot, point.context) + accessibility_highlights = highlight_accessibility_features(screenshot) + + # 3. Multi-Language Annotations + for lang in project_languages: + annotated_screenshot = add_localized_annotations( + screenshot, annotations, lang + ) + save_screenshot(f"screenshots/{lang}/{point.filename}", annotated_screenshot) + + # 4. Generate Screenshot Index + return create_screenshot_manifest(screenshot_points) +``` + +#### ๐Ÿ“ Accessibility Documentation Generator +```markdown +## Auto-Generated Accessibility Documentation + +### WCAG 2.1 Compliance Analysis +- **Level AA Compliance**: {{compliance_percentage}}% +- **Critical Issues**: {{critical_count}} identified +- **Recommendations**: {{recommendations_count}} generated + +### Accessibility Features Implemented +- **Keyboard Navigation**: {{keyboard_nav_analysis}} +- **Screen Reader Support**: {{screen_reader_analysis}} +- **Color Contrast**: {{contrast_analysis}} +- **Focus Management**: {{focus_analysis}} +- **ARIA Labels**: {{aria_analysis}} + +### User Impact Assessment +- **Vision Impairments**: {{vision_impact}} +- **Motor Impairments**: {{motor_impact}} +- **Cognitive Considerations**: {{cognitive_impact}} +- **Assistive Technology**: {{at_compatibility}} + +### Testing Recommendations +```bash +# Automated accessibility testing +npm run test:a11y -- --feature={{feature-name}} +npm run test:screen-reader +npm run test:keyboard-nav +``` + +### Accessibility User Journey +1. **Screen Reader Experience** + - Navigation path: {{sr_navigation}} + - Key announcements: {{key_announcements}} + - Potential issues: {{sr_issues}} + +2. **Keyboard-Only Experience** + - Tab order: {{tab_order}} + - Shortcuts available: {{shortcuts}} + - Focus indicators: {{focus_indicators}} +``` + +#### ๐ŸŒ Intelligent Multi-Language Generation +```yaml +# Language-aware documentation generation +multilingual_strategy: + content_adaptation: + spanish: + tone: "More formal, use 'usted' for user-facing docs" + structure: "Lead with benefits, then technical details" + code_comments: "Spanish comments for business logic" + + german: + tone: "Precise, structured, comprehensive" + structure: "Systematic, step-by-step approach" + technical_depth: "Higher technical detail expected" + + english: + tone: "Conversational but professional" + structure: "Task-oriented with quick wins" + + cultural_considerations: + date_formats: "DD.MM.YYYY (DE), DD/MM/YYYY (ES), MM/DD/YYYY (US)" + number_formats: "1.234,56 (DE/ES), 1,234.56 (US)" + currency: "โ‚ฌ (DE/ES), $ (US context)" +``` + +### Phase 4: Quality Assurance & Intelligence + +#### ๐Ÿ“Š Documentation Quality Scoring Engine +```python +class DocumentationQualityAnalyzer: + def calculate_quality_score(self, docs): + scores = { + 'completeness': self.analyze_completeness(docs), + 'clarity': self.analyze_readability(docs), + 'accuracy': self.verify_code_examples(docs), + 'accessibility': self.audit_accessibility_docs(docs), + 'maintainability': self.assess_maintainability(docs), + 'user_experience': self.evaluate_user_journey(docs), + 'technical_depth': self.assess_technical_coverage(docs), + 'cross_references': self.validate_links_and_refs(docs) + } + + weighted_score = self.calculate_weighted_average(scores) + improvements = self.generate_improvement_suggestions(scores) + + return QualityReport( + overall_score=weighted_score, + category_scores=scores, + improvement_plan=improvements, + benchmark_comparison=self.compare_to_industry_standards(scores) + ) +``` + +#### ๐Ÿ”„ Version-Aware Documentation System +```markdown +## Version Evolution Tracking + +### Feature Evolution Timeline +```mermaid +graph TD + A[v1.0: Basic Implementation] --> B[v1.1: UI Improvements] + B --> C[v1.2: Accessibility Enhancements] + C --> D[v2.0: Major Rewrite - Current] + + A -.-> A1[Legacy Docs] + B -.-> B1[Updated Docs] + C -.-> C1[A11y Docs Added] + D -.-> D1[Complete Refresh] +``` + +### Breaking Changes Documentation +| Version | Breaking Change | Migration Guide | Effort Level | +|---------|----------------|-----------------|--------------| +| v2.0 | API endpoint restructure | [Migration Guide](./migrations/v2.0.md) | High | +| v1.2 | CSS class renaming | [CSS Migration](./migrations/v1.2-css.md) | Medium | + +### Backward Compatibility Matrix +- **v1.x Support**: Until {{end_of_life_date}} +- **Migration Tools**: Auto-migration script available +- **Deprecation Warnings**: {{warning_count}} active warnings +``` + +#### ๐Ÿ”— Smart Project Management Integration +```javascript +// Auto-sync with project management tools +const pmIntegration = { + jira: { + createDocumentationTickets: () => { + // Auto-create tickets for screenshot capture + // Link documentation tasks to feature epic + // Set up review workflows + } + }, + + linear: { + updateFeatureStatus: () => { + // Mark documentation as complete + // Link docs to feature requirements + // Update project roadmap + } + }, + + github: { + createPullRequest: () => { + // Auto-create PR with generated docs + // Include quality score in PR description + // Set up automated reviews + } + } +} +``` + +### Phase 5: Advanced Output & Automation + +#### ๐ŸŽฏ Intelligent Summary Generation +```markdown +## ๐Ÿš€ Documentation Generation Complete! + +### ๐Ÿ“Š Quality Metrics +- **Overall Quality Score**: {{quality_score}}/100 ๐Ÿ† +- **Accessibility Compliance**: {{a11y_score}}% (WCAG 2.1 AA) +- **Multi-language Coverage**: {{language_count}} languages +- **Cross-reference Accuracy**: {{link_accuracy}}% + +### ๐Ÿ“ Generated Documentation +``` +docs/ +โ”œโ”€โ”€ dev/{{feature-name}}/ # Developer documentation ({{dev_word_count}} words) +โ”‚ โ”œโ”€โ”€ implementation.md # Core implementation (Quality: {{impl_quality}}/100) +โ”‚ โ”œโ”€โ”€ architecture.md # System design +โ”‚ โ”œโ”€โ”€ api-reference.md # API documentation +โ”‚ โ”œโ”€โ”€ accessibility.md # A11y implementation +โ”‚ โ””โ”€โ”€ testing-guide.md # Testing strategy +โ”œโ”€โ”€ user/{{feature-name}}/ # User documentation +โ”‚ โ”œโ”€โ”€ en/getting-started.md # English user guide ({{en_word_count}} words) +โ”‚ โ”œโ”€โ”€ es/guรญa-inicio.md # Spanish user guide ({{es_word_count}} words) +โ”‚ โ”œโ”€โ”€ de/erste-schritte.md # German user guide ({{de_word_count}} words) +โ”‚ โ””โ”€โ”€ screenshots/ # AI-generated screenshots ({{screenshot_count}} files) +โ””โ”€โ”€ accessibility/ + โ””โ”€โ”€ {{feature-name}}-audit.md # WCAG compliance report +``` + +### ๐ŸŽฏ Smart Insights +- **๐Ÿง  AI Analysis**: {{complexity_level}} complexity, {{pattern_count}} patterns detected +- **๐ŸŽจ Design Integration**: {{design_system}} components documented +- **๐Ÿ”’ Security Notes**: {{security_findings}} security considerations identified +- **โšก Performance**: {{performance_impact}} performance implications noted + +### ๐Ÿ“ˆ Improvement Opportunities +1. **{{top_improvement}}** (Impact: High) +2. **{{second_improvement}}** (Impact: Medium) +3. **{{third_improvement}}** (Impact: Low) + +### ๐Ÿค– AI Recommendations +- Consider adding {{ai_suggestion_1}} +- Documentation could benefit from {{ai_suggestion_2}} +- Users might appreciate {{ai_suggestion_3}} + +### ๐Ÿ”„ Next Steps +```bash +# Review generated documentation +git add docs/ +git commit -m "docs: Add comprehensive documentation for {{feature-name}} + +- Quality score: {{quality_score}}/100 +- Multi-language support: {{languages}} +- Accessibility compliant: {{a11y_compliance}}" + +# Deploy to documentation site +npm run docs:build +npm run docs:deploy + +# Update project management +{{pm_tool}} update-feature {{feature-name}} --docs-complete +``` + +### ๐ŸŽŠ Celebration Mode +``` +๐ŸŽธ Rock on! Your documentation is now as polished as your bass playing! + Quality Score: {{quality_score}}/100 - That's worthy of a D&D natural 20! ๐ŸŽฒ + + Ready to quest onward? This documentation will guide your users + through their hero's journey better than any dungeon master! ๐Ÿ‰ +``` +``` + +## ๐ŸŒŸ Advanced Features Showcase + +### ๐Ÿงช Experimental Features (Beta) +- **Video Documentation**: Auto-generate walkthrough videos with AI narration +- **Interactive Tutorials**: Embed interactive code examples +- **Smart Maintenance**: AI-powered documentation freshness detection +- **User Feedback Integration**: Real-time user feedback incorporation +- **Documentation Analytics**: Track documentation effectiveness + +### ๐Ÿ”ฎ Future Roadmap +- **AR Documentation**: Augmented reality overlay documentation +- **Voice-Activated Docs**: "Hey Claude, explain this feature" +- **Predictive Documentation**: AI predicts documentation needs before features are built +``` + +--- + +*This enhanced version leverages cutting-edge AI capabilities while maintaining practical utility. It's like having a documentation team that never sleeps, speaks multiple languages, and has perfect attention to detail! ๐Ÿš€* \ No newline at end of file