# Feature Documentation Workflow

**Last Updated:** 2026-01-08

Complete workflow for creating, updating, and maintaining product feature documentation.

## Overview

This workflow ensures consistent, high-quality feature documentation that serves as the single source of truth for Ordio features.

## When to Create Feature Documentation

Create feature documentation when:

- New feature is added to Ordio
- Feature is significantly enhanced
- Feature documentation doesn't exist yet
- Gap analysis identifies missing documentation

## Creating New Feature Documentation

### Step 1: Preparation

1. **Check Existing Documentation**
   - Search for existing docs: `grep -r "[feature-name]" docs/content/product-features/`
   - Check `PRODUCT_FEATURES_INVENTORY.md` for status
   - Review related product page: `v2/pages/product_[feature].php`

2. **Gather Information**
   - Read product page PHP file completely
   - Extract meta tags, schema, hero content
   - Identify JS/CSS files used
   - Review related features for integration points
   - Check `docs/data/product-features-extracted.json` if available

3. **Review Template**
   - Read `docs/DOCUMENTATION_TEMPLATES.md` (Product Feature Template section)
   - Review similar feature docs for patterns
   - Check `VISUAL_DOCUMENTATION_PLAN.md` for screenshot requirements

### Step 2: Create Documentation File

1. **File Naming**
   - Pattern: `[feature-slug]-documentation.md`
   - Example: `schichtplanung-documentation.md`
   - Location: `docs/content/product-features/`

2. **Initial Structure**
   - Copy template from `DOCUMENTATION_TEMPLATES.md`
   - Fill in Basic Information section
   - Add current date: `date +%Y-%m-%d`

3. **Content Creation**
   - Write Overview (1-2 paragraphs)
   - Create 3-6 detailed use cases
   - Define target audience (primary/secondary users, industries)
   - Document key functionality (core + advanced)
   - Document technical implementation (files, dependencies, APIs)
   - Create user experience flows (2+ flows)
   - Document UI components
   - Plan visual documentation (screenshots, diagrams)
   - Document maintenance requirements

### Step 3: Validation

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

2. **Manual Review**
   - Check all required sections present
   - Verify no placeholder text
   - Verify links work
   - Check cross-references
   - Verify dates are current

3. **Fix Issues**
   - Address validation warnings
   - Fix broken links
   - Complete incomplete sections
   - Update dates if needed

### Step 4: Update Inventories

1. **Update PRODUCT_FEATURES_INVENTORY.md**
   - Add feature to list
   - Mark documentation status
   - Add completion date

2. **Update Cross-References**
   - Add to related feature docs
   - Update product page documentation
   - Update README.md if needed

## Updating Existing Documentation

### Step 1: Identify Update Need

Updates may be triggered by:

- Product page content changes
- New features added to existing feature
- API changes
- User workflow changes
- User feedback
- Gap analysis findings

### Step 2: Review Current Documentation

1. **Read Complete File**
   - Understand current state
   - Identify what needs updating
   - Check related sections

2. **Compare with Source**
   - Review product page PHP file
   - Check for new features or changes
   - Verify technical details still accurate

### Step 3: Update Content

1. **Update Sections**
   - Update Overview if feature changed
   - Add new use cases if new scenarios
   - Update technical implementation if files/APIs changed
   - Update user flows if workflows changed
   - Update visual documentation if screenshots added

2. **Update Metadata**
   - Update "Last Updated" date: `date +%Y-%m-%d`
   - Update status if feature status changed
   - Update cross-references if needed

### Step 4: Validate Updates

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

2. **Review Changes**
   - Verify updates are accurate
   - Check no placeholder text introduced
   - Verify links still work
   - Check dates are current

## Maintenance Schedule

### Monthly Tasks

- Review documentation for accuracy
- Update as needed based on product changes
- Check for broken links

### Quarterly Tasks

- Run validation scripts
- Fix broken links
- Update dates if stale
- Review completeness

### Annual Tasks

- Comprehensive review of all docs
- Update all dates
- Review for new best practices
- Archive outdated information

## Quality Standards

### Completeness

- All 10 required sections present
- No placeholder text
- Detailed use cases (3-6 scenarios)
- Complete technical implementation
- Detailed user flows (2+ flows)

### Accuracy

- Information matches product pages
- File paths verified
- API endpoints accurate
- User flows match actual workflows
- Dates current

### Consistency

- Follows template structure
- Uses consistent formatting
- Cross-references updated
- Links validated

## Validation Checklist

Before marking documentation as complete:

- [ ] All required sections present
- [ ] Use cases include Scenario, Process, Benefits
- [ ] Target audience includes primary/secondary users and industries
- [ ] Technical implementation includes files, dependencies, API endpoints
- [ ] User experience includes detailed flows and UI components
- [ ] Visual documentation section present
- [ ] No placeholder text
- [ ] Last Updated date is current
- [ ] Cross-references to related documentation present
- [ ] Links validated (run validation script)
- [ ] Content accuracy verified
- [ ] Technical details match implementation

## Tools & Scripts

### Validation Script

```bash
python3 scripts/documentation/validate-feature-docs.py
```

**Output:** `docs/content/product-features/VALIDATION_REPORT.md`

### Gap Analysis Script

```bash
python3 scripts/documentation/gap-analysis-product-features.py
```

**Output:** `docs/content/product-features/GAP_ANALYSIS_REPORT.md`

### Date Check

```bash
date +%Y-%m-%d  # Get current date for Last Updated field
```

## Common Issues & Solutions

### Issue: Missing Sections

**Solution:** Use template from `DOCUMENTATION_TEMPLATES.md` and fill in all sections.

### Issue: Placeholder Text

**Solution:** Replace all "to be documented" text with actual content. Review similar feature docs for examples.

### Issue: Broken Links

**Solution:** Run validation script, fix broken links, verify paths are correct.

### Issue: Outdated Information

**Solution:** Review product page PHP file, update documentation to match current implementation.

### Issue: Incomplete Use Cases

**Solution:** Expand use cases to include Scenario, Process (numbered steps), and Benefits. Review existing use cases for format.

## Related Documentation

- [Documentation Templates](../../DOCUMENTATION_TEMPLATES.md) - Standard templates
- [Documentation Standards](../../DOCUMENTATION_STANDARDS.md) - File naming and structure
- [Documentation Maintenance Process](../../DOCUMENTATION_MAINTENANCE_PROCESS.md) - General maintenance
- [Visual Documentation Plan](VISUAL_DOCUMENTATION_PLAN.md) - Screenshot and diagram requirements
- [Content Enhancement Plan](CONTENT_ENHANCEMENT_PLAN.md) - Content improvement guidelines
- [Enhancement Summary](ENHANCEMENT_SUMMARY.md) - Recent enhancements summary

## Related Cursor Rules

- [product-features.mdc](../../../.cursor/rules/product-features.mdc) - Feature documentation patterns
- [product-pages.mdc](../../../.cursor/rules/product-pages.mdc) - Product page patterns
- [shared-patterns.mdc](../../../.cursor/rules/shared-patterns.mdc) - Universal copy guidelines
- [global.mdc](../../../.cursor/rules/global.mdc) - Global planning and quality standards