# Helpdesk Integration Workflow

**Last Updated:** 2026-01-09

This document outlines the process for integrating helpdesk content into product feature documentation on an ongoing basis.

## Overview

The helpdesk integration workflow ensures that product feature documentation stays up-to-date with the latest helpdesk articles, providing comprehensive, accurate, and user-focused documentation.

## When to Run Integration

### Regular Schedule

- **Monthly:** Review new helpdesk articles and integrate relevant content
- **Quarterly:** Comprehensive review of all helpdesk content for updates
- **After Major Feature Releases:** Integrate new helpdesk articles for new features

### Trigger Events

- New helpdesk articles published
- Existing helpdesk articles updated significantly
- Feature documentation gaps identified
- User feedback indicates missing workflows
- Product features updated or changed

## Integration Process

### Phase 1: Discovery

1. **Check Helpdesk for Updates:**
   ```bash
   # Navigate to helpdesk
   # Review new articles since last integration
   # Check for updated articles
   ```

2. **Identify Relevant Articles:**
   - Use `docs/content/helpdesk/HELPDESK_TO_FEATURE_MAPPING.md` as reference
   - Check which features have new or updated articles
   - Review article titles and previews for relevance

3. **Extract New Content:**
   ```bash
   # Run extraction script if needed
   python3 scripts/documentation/extract-helpdesk-systematic.py
   
   # Parse new content
   python3 scripts/documentation/parse-helpdesk-content.py
   ```

### Phase 2: Analysis

1. **Review Extracted Content:**
   - Read parsed markdown files: `docs/content/helpdesk/parsed/[category]/[article-slug].md`
   - Identify workflows, configurations, troubleshooting info
   - Note any new features or functionality

2. **Create Content Summaries:**
   ```bash
   # Generate extraction summaries
   python3 scripts/documentation/create-extraction-summaries.py
   ```

3. **Perform Gap Analysis:**
   ```bash
   # Compare helpdesk content with existing docs
   python3 scripts/documentation/gap-analysis-helpdesk.py
   ```

### Phase 3: Integration

1. **Select Target Documentation:**
   - Identify feature documentation file to enhance
   - Read existing documentation completely
   - Note current structure and content

2. **Plan Integration:**
   - Determine where new content fits
   - Identify what to add vs. what to update
   - Avoid redundancy with existing content

3. **Integrate Content:**
   - Add "Detailed Workflows from Helpdesk" section if not present
   - Extract step-by-step workflows from helpdesk articles
   - Enhance "Key Functionality" with new details
   - Update UI component descriptions if needed
   - Add troubleshooting sections where relevant

4. **Format Workflows:**
   ```markdown
   ### Detailed Workflows from Helpdesk

   #### Workflow: [Workflow Name]

   **Purpose:** [What this workflow accomplishes]

   **Steps:**

   1. [Step 1: Action description]
   2. [Step 2: What happens next]
   3. [Step 3: Final outcome]

   **Video Guide:** [Link if available]
   ```

### Phase 4: Validation

1. **Run Validation Script:**
   ```bash
   python3 scripts/documentation/validate-feature-docs.py
   ```

2. **Review Validation Results:**
   - Check for errors (must fix)
   - Review warnings (address if relevant)
   - Verify all sections present

3. **Manual Review:**
   - Read through integrated content
   - Verify workflows are accurate
   - Check for redundancy
   - Ensure formatting is consistent

4. **Update Metadata:**
   - Update "Last Updated" date: `date +%Y-%m-%d`
   - Update `PRODUCT_FEATURES_INVENTORY.md` if needed
   - Update `FEATURE_DOCUMENTATION_INDEX.md` if needed

### Phase 5: Documentation

1. **Update Tracking Files:**
   - Update `docs/content/helpdesk/ENHANCEMENT_COMPLETE.md`
   - Note which articles were integrated
   - Record integration date

2. **Update Mapping:**
   - Update `docs/content/helpdesk/HELPDESK_TO_FEATURE_MAPPING.md` if new mappings
   - Update extraction summaries if needed

## Integration Guidelines

### What to Integrate

✅ **DO Integrate:**
- Step-by-step workflows and how-to guides
- Configuration instructions
- Troubleshooting information
- Feature-specific details not in product pages
- Real-world examples and use cases
- UI component details and interactions

❌ **DON'T Integrate:**
- General navigation instructions
- Duplicate information already in docs
- Outdated or deprecated workflows
- Feature overviews (already in Overview section)
- Generic helpdesk navigation links

### Integration Best Practices

1. **Maintain Structure:**
   - Keep existing documentation structure
   - Add helpdesk workflows as new section
   - Don't reorganize existing content unnecessarily

2. **Preserve Context:**
   - Include purpose and benefits of workflows
   - Add context about when to use each workflow
   - Reference related features or workflows

3. **Avoid Redundancy:**
   - Check existing content before adding
   - Enhance existing sections rather than duplicating
   - Use cross-references instead of repeating content

4. **Keep Current:**
   - Verify helpdesk content is up-to-date
   - Remove outdated workflows
   - Update workflows if features changed

5. **Format Consistently:**
   - Use consistent workflow format
   - Follow existing documentation style
   - Include video guide links if available

## Example Integration

### Before Integration

```markdown
## User Experience

### Detailed User Flow

#### Flow 1: Creating a Schedule

1. Manager accesses Schichtplan section
2. Selects week to plan
3. Creates shifts
4. Assigns employees
```

### After Integration

```markdown
## User Experience

### Detailed User Flow

#### Flow 1: Creating a Schedule

1. Manager accesses Schichtplan section
2. Selects week to plan
3. Creates shifts
4. Assigns employees

### Detailed Workflows from Helpdesk

The following workflows are based on helpdesk documentation and provide step-by-step guides for common Schichtplanung tasks.

#### Workflow: Creating Shifts

**Purpose:** Set up new shifts in the schedule

**Steps:**

1. Navigate to Schichtplan section
2. Click "Neue Schicht" or "New Shift"
3. Select date and time range
4. Choose work area
5. Assign employees
6. Set shift requirements (skills, certifications)
7. Save shift

**Video Guide:** [Link to helpdesk video if available]
```

## Automation Scripts

### Available Scripts

1. **Extract Helpdesk Content:**
   ```bash
   python3 scripts/documentation/extract-helpdesk-systematic.py
   ```
   - Extracts all helpdesk pages
   - Saves to `docs/content/helpdesk/raw/helpdesk-content.json`

2. **Parse Content:**
   ```bash
   python3 scripts/documentation/parse-helpdesk-content.py
   ```
   - Converts HTML to markdown
   - Saves to `docs/content/helpdesk/parsed/[category]/[article-slug].md`

3. **Create Summaries:**
   ```bash
   python3 scripts/documentation/create-extraction-summaries.py
   ```
   - Generates structured summaries per feature
   - Saves to `docs/content/helpdesk/extractions/[feature-slug]-helpdesk-content.md`

4. **Gap Analysis:**
   ```bash
   python3 scripts/documentation/gap-analysis-helpdesk.py
   ```
   - Compares helpdesk content with existing docs
   - Generates gap analysis report

5. **Validate Documentation:**
   ```bash
   python3 scripts/documentation/validate-feature-docs.py
   ```
   - Validates all feature documentation
   - Checks for completeness and quality

## Troubleshooting

### Common Issues

**Issue: Helpdesk content doesn't match current system**

- **Solution:** Verify helpdesk article is current, check for updates, contact helpdesk maintainer if needed

**Issue: Workflow conflicts with existing documentation**

- **Solution:** Review both sources, verify which is correct, update both if needed, note discrepancies

**Issue: Too much redundancy**

- **Solution:** Focus on unique workflows, use cross-references, extract only new information

**Issue: Missing context**

- **Solution:** Add purpose and benefits, include when to use workflow, reference related features

## Related Documentation

- [Helpdesk Structure](HELPDESK_STRUCTURE.md) - Complete helpdesk structure
- [Helpdesk to Feature Mapping](HELPDESK_TO_FEATURE_MAPPING.md) - Mapping table
- [Enhancement Plan](ENHANCEMENT_PLAN.md) - Per-feature enhancement plan
- [Enhancement Complete](ENHANCEMENT_COMPLETE.md) - Completed enhancements summary
- [Gap Analysis](GAP_ANALYSIS.md) - Gap analysis results
- [Feature Documentation Workflow](../product-features/FEATURE_DOCUMENTATION_WORKFLOW.md) - Feature doc workflow

## Related Cursor Rules

- [product-features.mdc](../../../.cursor/rules/product-features.mdc) - Feature documentation patterns (includes helpdesk integration guidance)