ai-playbook 1.0.0

package/skills/documentation/examples.md

@@ -0,0 +1,364 @@
+# Documentation Skill - Examples
+
+## Example 1: Complete API Documentation
+
+**User Request**: "Create comprehensive documentation for this REST API that enables developers to integrate without support."
+
+**Expected Behavior**:
+- Document all endpoints (GET, POST, PUT, DELETE, PATCH)
+- Define path parameters, query parameters, and request body with types
+- Provide response format with example responses for success and error cases
+- Document all HTTP status codes (200, 201, 400, 401, 403, 404, 429, 500, etc.)
+- Explain authentication requirements (API keys, OAuth, JWT)
+- Document rate limiting (requests per minute, quota strategy)
+- Create code examples in 3+ languages (JavaScript, Python, curl)
+- Explain versioning strategy and deprecation policy
+- Create OpenAPI/Swagger specification
+- Include webhook documentation if applicable
+
+**Success Criteria**:
+- Developers can integrate without needing to ask questions
+- Code examples are runnable and tested
+- All endpoints documented with all HTTP methods
+- Error cases documented with recovery strategies
+- <5% of integration issues require documentation clarification
+
+---
+
+## Example 2: User Guide for Feature
+
+**User Request**: "Write a comprehensive user guide for this product feature that enables users to use it without training."
+
+**Expected Behavior**:
+- Create overview explaining feature purpose and benefits
+- Write step-by-step getting started guide (5-10 steps)
+- Create how-to guides for common use cases (3-5 scenarios)
+- Include screenshots or videos for each major step
+- Create troubleshooting section with common issues and solutions
+- Write FAQ addressing questions users typically ask
+- Include glossary explaining domain-specific terms
+- Create video walkthrough for complex features
+- Design for multiple user expertise levels
+- Include links to related features/documentation
+
+**Success Criteria**:
+- New users can use feature productively within 15 minutes
+- 80%+ of user questions answered in documentation
+- Support tickets related to feature reduced by 70%
+- Users rate documentation as helpful (>4/5 stars)
+
+---
+
+## Example 3: Architecture Decision Records (ADRs)
+
+**User Request**: "Document the architectural decision to use microservices with clear rationale and trade-offs."
+
+**Expected Behavior**:
+- Create ADR with standard format (status, context, decision, consequences)
+- Explain context that led to decision
+- Document alternatives considered (monolith, distributed monolith, etc.)
+- Explain chosen decision and rationale
+- Document consequences (positive and negative)
+- Explain effort/cost impact
+- Link to related decisions and architecture diagrams
+- Include date and decision makers
+- Create plan for review/revision
+- Make ADRs searchable and discoverable
+
+**Success Criteria**:
+- Future architects understand why decisions were made
+- Prevents recurring discussion of same decisions
+- Informs future architectural choices
+- Used as onboarding material for new architects
+
+---
+
+## Example 4: Getting Started Guide
+
+**User Request**: "Create a getting started guide that gets new developers productive in 30 minutes."
+
+**Expected Behavior**:
+- Assume minimal prerequisite knowledge
+- Provide environment setup (OS-specific if needed)
+- List all prerequisites with versions
+- Create step-by-step setup instructions
+- Provide working example (hello world)
+- Explain project structure
+- Document common commands
+- Create troubleshooting section for setup issues
+- Explain next steps for deeper learning
+- Provide links to next documentation sections
+- Include estimated time for each section
+
+**Success Criteria**:
+- New developers set up environment in <30 minutes
+- 95%+ success rate without support help
+- Clear next steps guide deeper learning
+- Setup issues resolved from documentation
+
+---
+
+## Example 5: Troubleshooting Guide
+
+**User Request**: "Create a troubleshooting guide for common issues that reduces support tickets."
+
+**Expected Behavior**:
+- Document top 15-20 most common issues
+- For each issue: symptoms, root causes, solutions
+- Provide step-by-step diagnostic procedures
+- Include code examples showing issues and fixes
+- Design guide for users with different expertise levels
+- Create flowchart for issue diagnosis
+- Include log analysis tips and error message explanations
+- Link to related issues
+- Include when to escalate to support
+- Create searchable by symptom, error message, and issue name
+
+**Success Criteria**:
+- Users resolve 80%+ of issues from documentation
+- Support team spends <5% time on documented issues
+- User satisfaction with self-service troubleshooting >4/5
+- Support tickets related to common issues reduced by 75%
+
+---
+
+## Example 6: Migration Guide
+
+**User Request**: "Create a migration guide helping users upgrade from version 2.0 to 3.0 with breaking changes."
+
+**Expected Behavior**:
+- Clearly state breaking changes
+- Document migration steps in logical order
+- Provide before/after code examples
+- Create deprecation timeline
+- Explain benefits of upgrading
+- Document backward compatibility period
+- Provide rollback procedure if needed
+- Include common migration issues and solutions
+- Create testing strategy for migration
+- Provide automated migration tools if applicable
+- Design guide for different data sizes/scenarios
+
+**Success Criteria**:
+- 95%+ of users successfully migrate without issues
+- Migration takes <expected time
+- Zero production incidents from migration
+- Users understand deprecation timeline and plan accordingly
+
+---
+
+## Example 7: API Reference Documentation
+
+**User Request**: "Generate API reference documentation from OpenAPI specification with examples."
+
+**Expected Behavior**:
+- Generate API documentation from OpenAPI/Swagger spec
+- Create endpoint pages with detailed parameter descriptions
+- Include request/response example for each endpoint
+- Document authentication requirements per endpoint
+- Show rate limiting per endpoint
+- Create sidebar navigation for endpoint discovery
+- Include search functionality
+- Create change log for API versions
+- Link related endpoints
+- Include code examples in multiple languages
+
+**Success Criteria**:
+- Developers find endpoints and understand parameters
+- Code examples are immediately usable
+- API specification and documentation synchronized
+- <5% of API integration questions
+
+---
+
+## Example 8: Knowledge Base Implementation
+
+**User Request**: "Build a searchable knowledge base that helps users find answers without contacting support."
+
+**Expected Behavior**:
+- Design content hierarchy with clear categories
+- Create 50+ articles covering product features and common issues
+- Implement full-text search with relevance ranking
+- Create article templates for consistency
+- Design feedback mechanism on article helpfulness
+- Create related articles recommendations
+- Implement article ratings/comments
+- Create analytics to track article usage and gaps
+- Design editorial calendar for content updates
+- Create contributor guidelines
+
+**Success Criteria**:
+- 70%+ of user questions answered by knowledge base
+- Average article helpfulness rating >4/5
+- Support tickets reduced by 50%
+- Users find answers in <2 minutes on average
+
+---
+
+## Example 9: Configuration Documentation
+
+**User Request**: "Document all configuration options with clear examples for different use cases."
+
+**Expected Behavior**:
+- List all configuration parameters with types and defaults
+- Explain effect of each configuration on system behavior
+- Provide examples for common configuration scenarios
+- Document configuration precedence (CLI > env > config file)
+- Create performance impact analysis for key settings
+- Document environment-specific configurations
+- Include security implications of settings
+- Provide sample configurations for different deployment types
+- Document deprecated configuration options with migration path
+- Create validation rules and constraints
+
+**Success Criteria**:
+- Users understand configuration options without experimenting
+- Configuration errors reduced by 80%
+- Users find configuration examples for their use case
+- Performance tuning guidance reduces support questions
+
+---
+
+## Example 10: Runbook for Operations
+
+**User Request**: "Create operational runbooks for common tasks and incident responses."
+
+**Expected Behavior**:
+- Document step-by-step procedures for common operational tasks
+- Create incident response playbooks for critical issues
+- Include decision trees for troubleshooting
+- Document alerting criteria and escalation paths
+- Provide commands with expected outputs
+- Include prerequisites and dependencies
+- Document rollback procedures for each task
+- Create contact and escalation procedures
+- Include safety checks and validation steps
+- Document timing and impact of each step
+
+**Success Criteria**:
+- Operations team executes procedures without errors
+- MTTR (mean time to recovery) reduced by 50%
+- Runbooks used for 95%+ of operational tasks
+- Incident severity reduced through better response
+
+---
+
+## Example 11: Release Notes Template
+
+**User Request**: "Create release notes that clearly communicate changes and required actions to users."
+
+**Expected Behavior**:
+- Organize changes by category (features, improvements, fixes, breaking changes)
+- Clearly highlight breaking changes with migration path
+- Include impact assessment (who is affected)
+- Document upgrade/deployment procedure
+- Include known issues and limitations
+- Provide rollback procedure if needed
+- Link to detailed documentation
+- Include security update information
+- Document deprecations with timeline
+- Provide download links
+
+**Success Criteria**:
+- Users understand what changed and if it affects them
+- Upgrade decisions informed by release notes
+- 0% unplanned outages due to upgrade surprises
+- Users successfully upgrade without issues
+
+---
+
+## Example 12: Deployment Documentation
+
+**User Request**: "Document the deployment process enabling teams to deploy safely and consistently."
+
+**Expected Behavior**:
+- Document prerequisites and requirements
+- Create step-by-step deployment procedure
+- Document pre-deployment checklist
+- Include rollback procedure
+- Create health check procedures
+- Document deployment timing and maintenance windows
+- Include performance validation after deployment
+- Document configuration changes needed
+- Include backup/restore procedures
+- Create environment-specific deployment procedures
+
+**Success Criteria**:
+- Teams deploy consistently without errors
+- Deployments predictable with clear timeline
+- Rollback executed in <5 minutes if needed
+- Zero production incidents from deployments
+
+---
+
+## Example 13: Video Tutorial Series
+
+**User Request**: "Create 10 video tutorials covering key features and common workflows."
+
+**Expected Behavior**:
+- Create 5-15 minute videos for each major feature
+- Show real examples users will recognize
+- Use clear narration explaining steps
+- Include captions/transcripts for accessibility
+- Show common mistakes and how to avoid them
+- Link to related written documentation
+- Include practice exercises
+- Create playlists for learning paths
+- Design progressive difficulty levels
+- Include related articles in video descriptions
+
+**Success Criteria**:
+- Users prefer videos for learning (>70% of learners)
+- Video completion rate >70%
+- Users apply knowledge from videos successfully
+- Support questions reduced for video-covered topics
+
+---
+
+## Example 14: Style Guide & Standards
+
+**User Request**: "Create a documentation style guide ensuring consistency across all documentation."
+
+**Expected Behavior**:
+- Document voice and tone guidelines
+- Define heading hierarchy and structure
+- Create code example standards
+- Document link conventions
+- Define terminology standards (glossary)
+- Create formatting conventions (bold, italics, code)
+- Document screenshot/diagram standards
+- Define audience level indicators
+- Create update procedures and ownership
+- Document deprecated concepts and migration paths
+
+**Success Criteria**:
+- Documentation has consistent look and feel
+- Writers follow standards without guidance
+- Documentation more maintainable and searchable
+- Users can scan consistently
+
+---
+
+## Example 15: FAQ & Knowledge Articles
+
+**User Request**: "Create comprehensive FAQ addressing common user questions."
+
+**Expected Behavior**:
+- Compile 30-50 most common user questions
+- Write clear, concise answers
+- Link answers to related documentation
+- Organize by category/feature
+- Include cross-references
+- Add search keywords for discoverability
+- Include code examples where helpful
+- Link to troubleshooting if applicable
+- Update based on support tickets
+- Include feedback mechanism
+
+**Success Criteria**:
+- 80%+ of common questions answered
+- Support team uses FAQ for common questions
+- Users find answers without escalation
+- Support tickets reduced for FAQ-covered questions
+
+---

package/skills/documentation/skill.md

@@ -0,0 +1,200 @@
+# Documentation Skill
+
+## Purpose
+
+The Documentation skill enables the creation and maintenance of clear, comprehensive technical documentation that enables engineers, users, and stakeholders to understand, use, and maintain software systems effectively. This skill encompasses API documentation, user guides, architecture documentation, knowledge bases, and governance processes that ensure documentation evolves alongside systems. Quality documentation reduces support burden, accelerates onboarding, and enables self-service problem-solving.
+
+---
+
+## Table of Contents
+
+1. [Core Competencies](#core-competencies)
+2. [Specific Domains & Tools](#specific-domains--tools)
+3. [Best Practices](#best-practices)
+4. [Deliverables](#deliverables)
+5. [Success Criteria](#success-criteria)
+
+---
+
+## Core Competencies
+
+### 1. **API Documentation**
+Document APIs comprehensively with request/response examples, error codes, and usage patterns. Create OpenAPI/Swagger specifications that serve as both documentation and API contracts. Provide code examples in multiple languages. Maintain API documentation as APIs evolve.
+
+**Application**: RESTful API docs, GraphQL schema documentation, SDK documentation, webhook documentation.
+
+### 2. **User Guides & Tutorials**
+Create step-by-step guides that help users accomplish goals. Write tutorials for common use cases. Provide getting-started guides for new users. Structure guides for different user expertise levels. Include screenshots and videos.
+
+**Application**: Feature guides, configuration guides, troubleshooting guides, video tutorials, interactive walkthroughs.
+
+### 3. **Architecture Documentation**
+Document system design, component relationships, and architectural decisions. Create diagrams that explain system structure. Explain trade-offs and alternatives considered. Document evolution strategy and roadmap.
+
+**Application**: C4 model documentation, component diagrams, Architecture Decision Records (ADRs), data flow diagrams.
+
+### 4. **Technical Writing & Clarity**
+Write clear, concise documentation that serves its audience. Use active voice and simple language. Structure content for scanability. Ensure consistency in terminology. Review for clarity and grammar.
+
+**Application**: Creating all documentation types, editing for clarity, establishing style guides, improving readability.
+
+### 5. **Knowledge Base Management**
+Build searchable knowledge bases that organize documentation hierarchically. Create consistent navigation. Establish version control for documentation. Design for easy content discovery.
+
+**Application**: Documentation sites, internal wikis, knowledge base systems, help centers.
+
+### 6. **Examples & Code Samples**
+Create working code examples that users can learn from and adapt. Provide examples in multiple languages/frameworks. Keep examples up-to-date and testable. Explain key concepts in examples.
+
+**Application**: Code snippets, complete working examples, sample configurations, boilerplate projects.
+
+### 7. **Troubleshooting & FAQ**
+Create FAQ sections that address common questions. Document common issues and solutions. Design troubleshooting guides that help users diagnose problems. Anticipate user confusion points.
+
+**Application**: FAQ sections, troubleshooting guides, common issues documentation, error message explanations.
+
+### 8. **Release Notes & Changelog**
+Document changes in each release with user impact clearly stated. Highlight breaking changes and migration paths. Organize by feature, fix, and deprecation. Create upgrade guides.
+
+**Application**: Release notes, changelog maintenance, migration guides, deprecation notices.
+
+### 9. **Onboarding Documentation**
+Create documentation that helps new users and team members get up to speed quickly. Design learning paths. Create environment setup guides. Design progressive onboarding.
+
+**Application**: Getting started guides, environment setup, first-run documentation, team onboarding guides.
+
+### 10. **API Contract Documentation**
+Document API contracts that enable independent evolution. Use standard formats (OpenAPI, GraphQL schema). Keep contracts synchronized with implementation. Use contracts to generate documentation.
+
+**Application**: OpenAPI specifications, GraphQL schema documentation, API contracts, interface documentation.
+
+### 11. **Configuration Documentation**
+Document all configuration options with their effects and defaults. Explain configuration precedence and priority. Provide examples for different scenarios. Document environment-specific configurations.
+
+**Application**: Configuration guides, environment variable documentation, settings documentation, customization guides.
+
+### 12. **Deployment & Operations Documentation**
+Document deployment procedures and operational processes. Create runbooks for common operational tasks. Document monitoring and alerting. Provide incident response procedures.
+
+**Application**: Deployment guides, runbooks, operational procedures, incident response guides.
+
+### 13. **Decision & Context Documentation**
+Create Architecture Decision Records that explain why decisions were made. Document context that informed decisions. Explain alternatives considered. Update as decisions evolve.
+
+**Application**: ADRs, design documents, RFC (Request for Comments) documents, decision logs.
+
+### 14. **Diagrams & Visual Documentation**
+Create diagrams that clarify concepts. Use appropriate diagram types (flowcharts, sequence, class, architecture). Keep diagrams synchronized with text. Make diagrams accessible.
+
+**Application**: System architecture diagrams, data flow diagrams, sequence diagrams, entity relationship diagrams.
+
+### 15. **Documentation Tools & Automation**
+Use tools that enable version control, searchability, and collaboration. Automate documentation generation from code. Implement broken link checking. Automate deployment of documentation.
+
+**Application**: MkDocs, Hugo, Sphinx, OpenAPI tools, documentation generators.
+
+### 16. **Glossary & Terminology**
+Create glossaries that define domain-specific terms. Maintain consistent terminology across documentation. Explain acronyms and abbreviations. Help users understand new concepts.
+
+**Application**: Glossaries, term definitions, concept explanations, abbreviation guides.
+
+### 17. **Accessibility in Documentation**
+Create documentation accessible to all users including those with disabilities. Use proper heading hierarchy. Provide alt text for images. Ensure color contrast. Support screen readers.
+
+**Application**: WCAG-compliant documentation, alt text for images, caption videos, accessible diagrams.
+
+### 18. **Documentation Maintenance & Governance**
+Establish processes to keep documentation accurate and current. Assign ownership. Create review processes. Plan for deprecation. Track user feedback. Measure documentation effectiveness.
+
+**Application**: Documentation review process, update schedules, owner assignments, feedback collection.
+
+---
+
+## Specific Domains & Tools
+
+### Documentation Platforms
+- **MkDocs**: Python-based static documentation site generator
+- **Hugo**: General-purpose static site generator
+- **Sphinx**: Documentation generator originally for Python projects
+- **Docusaurus**: React-based documentation site generator
+- **Confluence**: Enterprise wiki and collaboration platform
+- **Notion**: All-in-one workspace for documentation and notes
+
+### API Documentation Tools
+- **OpenAPI/Swagger**: Standard for API specification and documentation
+- **Postman**: API documentation and testing
+- **Stoplight**: API design, documentation, and testing
+- **Redoc**: Beautiful API documentation generator
+- **GraphQL**: Built-in schema introspection and documentation
+
+### Diagramming Tools
+- **Mermaid**: ASCII-art-style diagrams in Markdown
+- **Draw.io**: Web-based diagramming tool
+- **Lucidchart**: Collaborative diagramming
+- **PlantUML**: Text-based UML diagram generation
+
+### Supporting Tools
+- **Git**: Version control for documentation
+- **Algolia**: Fast search for documentation
+- **Netlify/Vercel**: Documentation site hosting and deployment
+- **GitHub Pages**: Free documentation hosting
+- **Vale**: Prose linting for consistency
+
+---
+
+## Best Practices
+
+1. **Write for Your Audience**: Understand your readers' expertise levels and goals. Tailor content accordingly.
+
+2. **Keep Documentation Current**: Establish processes to update documentation when code changes. Make docs part of definition of done.
+
+3. **Provide Working Examples**: Give complete, executable examples that readers can learn from and run.
+
+4. **Use Consistent Terminology**: Define terms and use them consistently. Create glossaries for domain-specific terms.
+
+5. **Structure for Scannability**: Use clear headings, short paragraphs, and visual formatting. Readers scan, not read linearly.
+
+6. **Single Source of Truth**: Avoid duplicating information. Link to authoritative sources instead.
+
+7. **Version with Code**: Keep documentation in sync with code versions. Version documentation with software releases.
+
+8. **Seek Feedback**: Ask users what documentation helped/didn't help. Iterate based on feedback.
+
+9. **Test Examples**: Verify that code examples work. Automate example testing when possible.
+
+10. **Make It Searchable**: Use clear titles and headings. Include relevant keywords. Implement site search.
+
+---
+
+## Deliverables
+
+- **API Documentation**: Complete endpoint documentation with examples and error codes
+- **User Guides**: Step-by-step guides for common tasks and features
+- **Getting Started Guide**: Quick start for new users with minimal prerequisites
+- **Architecture Documentation**: System design, components, and integration architecture
+- **Code Examples**: Working examples in relevant languages and frameworks
+- **Troubleshooting Guide**: Common issues and solutions
+- **FAQ**: Answers to frequently asked questions
+- **Release Notes**: Changes in each release with user impact highlighted
+- **Deployment Guide**: Procedures for deploying and configuring systems
+- **Runbooks**: Procedures for common operational tasks
+- **Architecture Decision Records**: Documented decisions with rationale
+- **Glossary**: Domain-specific terms and definitions
+- **Video Tutorials**: Recorded walkthroughs of common tasks
+- **Style Guide**: Writing conventions and documentation standards
+- **Documentation Site**: Searchable, well-organized documentation
+
+---
+
+## Success Criteria
+
+1. **Accessibility**: Users can find documentation they need within 2-3 clicks
+2. **Clarity**: New users understand concepts without requiring support
+3. **Completeness**: Documentation answers questions users ask
+4. **Accuracy**: Documentation matches current code/system behavior
+5. **Freshness**: Documentation updated within 2 weeks of code changes
+6. **Searchability**: Users find relevant documentation through search
+7. **Engagement**: Users reference documentation rather than asking for help
+8. **Onboarding**: New team members productive within expected timeframe
+9. **Maintainability**: Documentation easy to update and version
+10. **Impact**: Reduced support tickets, faster issue resolution, less onboarding time