Skip to main content

JIRA Documentation Automation Workflow

This document explains how the automated documentation generation system works using Claude Code CLI to directly modify the Docusaurus website.

Overview​

The automation system uses Claude Code CLI to intelligently analyze and modify the documentation website based on JIRA requirements. Claude has direct repository access and can explore, understand, and modify the codebase autonomously.

Architecture: Claude Code CLI Integration​

Why Claude Code CLI?​

  • Full Repository Context: Claude can explore the entire repository using Read, Glob, and Grep tools
  • Direct File Modifications: Uses Write, Edit, and MultiEdit tools to modify files directly
  • Interactive Analysis: Can analyze existing patterns and maintain consistency
  • No Token Limits: Unlimited repository exploration without API restrictions
  • Structured Output: Stream-JSON format provides trackable operations

Workflow Steps​

1. JIRA Issue Creation​

  • Create a JIRA issue for documentation needs
  • Add the auto-doc label to trigger automation
  • Optional: Add specific doc type labels (doc:api, doc:user-guide, doc:release-notes, doc:feature)
  • Include detailed requirements in the issue description

2. Automated Branch Creation​

  • JIRA automation creates a branch named auto-doc/ISSUE-KEY (e.g., auto-doc/AI-78)
  • Branch is automatically pushed to Bitbucket repository

3. Pipeline Execution with Claude Code CLI​

The Bitbucket Pipeline performs these steps:

Step 1: Environment Setup​

# Install Claude Code CLI via npm (requires Node.js 18+)
- npm install -g @anthropic-ai/claude-code
- claude --version

# Validate Repository Variables
- node scripts/validate-environment.js

Step 2: Claude Code Automation​

# Extract issue key and run automation
- export ISSUE_KEY=${BITBUCKET_BRANCH#auto-doc/}
- python3 scripts/claude-documentation-automation.py --jira-id $ISSUE_KEY

4. Claude Code Repository Analysis​

Claude Code performs intelligent repository analysis:

Phase 1: Structure Discovery​

# Claude uses these tools automatically:
claude --output-format stream-json << EOF
Please analyze this Docusaurus documentation repository:
1. Use glob to understand the directory structure
2. Read sample documentation files to understand patterns
3. Analyze sidebar configurations and navigation
EOF

Phase 2: Content Pattern Recognition​

  • Product Structure: Identifies cyber, dellcyber, datasecurityessential products
  • Category Organization: Understands datasecurity, disasterrecovery, airgap categories
  • Section Patterns: Recognizes getting_started, managing_the_solution, reference sections
  • Content Templates: Analyzes existing documentation formats and styles

Phase 3: Intelligent Placement​

Claude determines optimal placement based on:

  • JIRA issue product labels
  • Content type requirements
  • Existing documentation structure
  • Navigation patterns

5. Direct File Modifications​

Claude Code makes direct changes to the repository:

Content Creation​

# Example operations Claude performs:
Write: solutions/cyber/datasecurity/managing_the_solution/configuration/new-feature/new-feature.md
Edit: sidebars/sidebar_cyber.ts  # Add navigation entry
Write: solutions/cyber/datasecurity/managing_the_solution/configuration/new-feature/_category_.json
  • Automatically updates sidebar configurations
  • Maintains proper category ordering
  • Ensures consistent navigation structure

6. Automated Commit and PR Creation​

The automation script:

  • Parses Claude's stream-JSON output
  • Commits all file modifications
  • Creates descriptive pull request
  • Updates JIRA with PR link

Script Components​

Core Automation Script​

claude-documentation-automation.py​

  • Purpose: Main orchestration script using Claude Code CLI
  • Functions:
    • Install and locate Claude Code binary
    • Fetch JIRA issue requirements
    • Execute Claude with repository context
    • Parse stream-JSON output for file operations
    • Handle commit and PR creation

claude-code-executor.py​

  • Purpose: Claude Code CLI interface
  • Functions:
    • Detect Claude Code installation
    • Execute prompts with stream-JSON output
    • Parse tool usage results (Write, Edit, MultiEdit)
    • Handle execution errors and timeouts

jira-integration.py (Enhanced)​

  • Purpose: JIRA API integration with placement logic
  • Functions:
    • Fetch issue details and parse requirements
    • Determine documentation placement strategy
    • Extract content type and target product
    • Update issues with automation results

Documentation Types & Placement Logic​

API Documentation​

  • Trigger: doc:api label
  • Placement: solutions/{product}/reference/api/{endpoint}/
  • Pattern: Technical reference with code examples

Configuration Guides​

  • Trigger: Configuration-related content in description
  • Placement: solutions/{product}/{category}/managing_the_solution/configuration/{feature}/
  • Pattern: Step-by-step setup instructions

User Guides​

  • Trigger: doc:user-guide label or default
  • Placement: solutions/{product}/{category}/getting_started/ or /managing_the_solution/
  • Pattern: Tutorial-style documentation

Release Notes​

  • Trigger: doc:release-notes label
  • Placement: solutions/{product}/whats_new/release_notes/
  • Pattern: Categorized changelog format

Claude Code Capabilities​

Repository Exploration​

# Claude can autonomously execute:
- glob("solutions/**/*.md")  # Discover all documentation
- read("solutions/cyber/datasecurity/managing_the_solution/configuration/example/example.md")
- grep("configuration", pattern="solutions/**/*.md")  # Find related content

Content Generation​

# Claude creates contextually appropriate content:
- Analyzes existing similar documentation
- Follows established formatting patterns
- Maintains consistent navigation structure
- Uses appropriate technical depth for audience

Quality Assurance​

# Claude performs built-in validation:
- Ensures markdown syntax correctness
- Validates internal link references
- Maintains documentation hierarchy
- Follows Superna style guidelines

Required Repository Variables​

Configure in Bitbucket Repository Settings → Repository Variables:

VariableTypePurpose
JIRA_URLRegularAtlassian instance URL
JIRA_EMAILRegularService account email
JIRA_API_TOKENSecuredJIRA API authentication
BITBUCKET_TOKENSecuredRepository and PR management
BITBUCKET_WORKSPACERegularBitbucket workspace name
BITBUCKET_REPO_SLUGRegularRepository identifier

Note: No Anthropic API key required - Claude Code CLI handles authentication

Pipeline Configuration​

Updated bitbucket-pipelines.yml​

'auto-doc/*':
  - step:
      runs-on:
        - self.hosted
      size: 2x
      name: Generate Documentation with Claude Code
      script:
        # Install Claude Code CLI
        - curl -L https://claude.ai/download/claude-linux -o claude
        - chmod +x claude && sudo mv claude /usr/local/bin/claude

        # Install Python dependencies
        - pip3 install requests python-dotenv

        # Validate environment
        - python3 scripts/validate-environment.py

        # Run Claude Code automation
        - export ISSUE_KEY=${BITBUCKET_BRANCH#auto-doc/}
        - python3 scripts/claude-documentation-automation.py --jira-id $ISSUE_KEY

      artifacts:
        - solutions/**/*.md
        - sidebars/**/*.ts
        - tmp/ai_generation_debug_*.log

Error Handling and Debugging​

Automated Diagnostics​

  • Stream-JSON Parsing: Validates Claude's tool usage output
  • File Operation Tracking: Monitors all Write, Edit, MultiEdit operations
  • Debug Logging: Comprehensive logs of Claude's analysis and decisions
  • Pipeline Artifacts: Debug logs preserved for troubleshooting

Common Issues and Solutions​

Claude Code CLI Not Found

# Install via npm (requires Node.js 18+):
npm install -g @anthropic-ai/claude-code
claude --version

Repository Variables Missing

# Validation script checks all required variables
python3 scripts/validate-environment.py

File Operation Failures

# Debug logs show exactly what Claude attempted:
# - File paths it tried to create/modify
# - Content it tried to write
# - Tool operations and their results

Advantages Over API Approach​

Repository Understanding​

  • ✅ Full Context: Claude can read any file, understand relationships
  • ✅ Pattern Recognition: Analyzes existing docs to maintain consistency
  • ✅ Interactive Exploration: Can discover and understand codebase autonomously
  • ✅ No Token Limits: Unlimited exploration of repository structure

Content Quality​

  • ✅ Contextual Accuracy: Understands existing patterns and follows them
  • ✅ Consistent Formatting: Maintains established documentation styles
  • ✅ Proper Navigation: Updates sidebars and maintains site structure
  • ✅ Technical Precision: Can reference actual code and configurations

Operational Benefits​

  • ✅ Direct Modifications: No manual parsing of API responses required
  • ✅ Atomic Operations: All changes tracked through stream-JSON output
  • ✅ Cost Effective: No API token costs for repository analysis
  • ✅ Pipeline Native: Integrates seamlessly with existing CI/CD

Testing and Validation​

Local Testing​

# Test Claude Code installation
claude --version

# Test automation script
python3 scripts/claude-documentation-automation.py --jira-id AI-78 --dry-run

# Validate Repository Variables
python3 scripts/validate-environment.py

Pipeline Testing​

  1. Create test JIRA issue with auto-doc label
  2. Monitor pipeline execution in Bitbucket
  3. Review generated files and PR content
  4. Check debug logs for Claude's analysis process

Future Enhancements​

Advanced Claude Capabilities​

  • Multi-file Documentation: Complex features requiring multiple related files
  • Cross-reference Updates: Automatically update related documentation
  • Version Management: Handle versioned documentation updates
  • Screenshot Integration: Placeholder generation for UI documentation

Workflow Improvements​

  • Draft Mode: Generate content for review before committing
  • Template Customization: Product-specific documentation templates
  • Bulk Operations: Process multiple JIRA issues in sequence
  • Quality Metrics: Automated content quality assessment

This workflow provides an intelligent, context-aware documentation automation system that understands your repository structure and creates high-quality, properly integrated documentation updates.