# product-features Full Instructions

## Product Feature Documentation Purpose

Document Ordio product features comprehensively for AI agents, developers, and content creators. Feature documentation serves as the single source of truth for feature capabilities, use cases, technical implementation, and user experience.

## Documentation Structure Requirements

### Required Sections

All feature documentation files must include these sections:

1. **Basic Information** - Feature name, slug, status, related pages
2. **Overview** - Brief description, purpose, value proposition
3. **Use Cases** - 3-6 detailed scenarios with processes and benefits
4. **Target Audience** - Primary/secondary users, industries
5. **Key Functionality** - Core capabilities and advanced features
6. **Technical Implementation** - Files, dependencies, API endpoints
7. **User Experience** - User flows, UI components
8. **Visual Documentation** - Screenshots, diagrams (planned or existing)
9. **Maintenance** - Update schedule, common updates
10. **Related Documentation** - Cross-references to related docs

### Section Quality Standards

**Use Cases:**

- Must include Scenario, Process (numbered steps), and Benefits
- Minimum 3 use cases, ideally 5-6
- Real-world scenarios, not generic descriptions
- Industry-specific examples where relevant

**Target Audience:**

- Primary users: Who uses this daily
- Secondary users: Who benefits occasionally
- Industries: Which industries benefit most
- User personas with responsibilities and benefits

**Technical Implementation:**

- Specific file paths (PHP, JS, CSS)
- Line counts for PHP files
- Complete dependency lists
- API endpoints with methods and purposes
- Integration details

**User Experience:**

- Minimum 2 detailed user flows
- UI component descriptions with layout, elements, interactions
- Visual design notes

## Documentation Quality Checklist

Before marking documentation as complete:

- [ ] All 10 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 (screenshots/diagrams planned or existing)
- [ ] No placeholder text ("to be documented", "TBD", etc.)
- [ ] Last Updated date is current (check with `date +%Y-%m-%d`)
- [ ] Cross-references to related documentation present
- [ ] Links validated (run `validate-feature-docs.py`)

## Content Standards

### Use Case Format

```markdown
### [Use Case Name]

**Scenario:** [Real-world scenario - 1-2 sentences]

**Process:**

1. [Step 1: What user does]
2. [Step 2: What happens next]
3. [Step 3: Final outcome]

**Benefits:** [Specific, measurable outcome]
```

**Example:**

```markdown
### Restaurant Scheduling

**Scenario:** A restaurant chain with 5 locations needs to schedule kitchen and service staff for the upcoming week.

**Process:**

1. Manager accesses Schichtplan section and selects the week to plan
2. Views availability of all staff members across locations
3. Uses shift templates for recurring patterns (e.g., Friday dinner rush)
4. Assigns staff based on skills (chef, server, bartender)
5. Reviews labor costs to stay within budget
6. Publishes schedule - staff receive notifications via mobile app

**Benefits:** Reduces planning time from 4 hours to 1 hour per week, ensures proper coverage during peak hours.
```

### Target Audience Format

```markdown
### Primary Users

**[User Role]:**

- [Responsibility/need]
- [Benefit they get]
- [How they use the feature]

### Secondary Users

**[User Role]:**

- [How they benefit]
- [When they use it]

### Industries

**[Industry]:**

- [Why this industry benefits]
- [Specific use case]
```

### Technical Implementation Format

```markdown
### Files

**Frontend Files:**

- **PHP:** `v2/pages/[file].php` (~[line count] lines)
  - [Description of what the file contains]
- **JavaScript:** `v2/js/[file].js` (if exists)
- **CSS:** `/v2/css/[file].min.css`

**Dependencies:**

**Backend Systems:**

- [System 1]
- [System 2]

**External Integrations:**

- [Integration 1]
- [Integration 2]

### API Endpoints

**[Category]:**

- `METHOD /api/[endpoint]` - [Purpose]
- `METHOD /api/[endpoint]` - [Purpose]
```

## Visual Documentation Requirements

### Screenshots

**Required for each feature:**

- Dashboard/main view screenshot
- Mobile app screenshot (if applicable)
- Key workflow screenshot

**Format:**

- WebP format (better compression)
- Maximum 1920px width
- Optimized for web (85-90% quality)
- Descriptive alt text

**Naming Convention:**

- `[feature-slug]-[view-type].webp`
- Example: `schichtplanung-calendar.webp`

### Diagrams

**Required diagrams:**

- User flow diagram (step-by-step process)
- Integration diagram (how feature connects to other systems)

**Format:**

- SVG preferred (scalable)
- PNG acceptable for complex diagrams
- Tools: Mermaid (for markdown), Draw.io, or similar

## Helpdesk Content Integration

### Using Helpdesk Content for Documentation

When enhancing feature documentation with helpdesk content:

1. **Identify Relevant Helpdesk Articles:**

   - Check `docs/content/helpdesk/HELPDESK_TO_FEATURE_MAPPING.md` for mapped articles
   - Review `docs/content/helpdesk/extractions/[feature-slug]-helpdesk-content.md` for structured summaries
   - Use parsed markdown files: `docs/content/helpdesk/parsed/[category]/[article-slug].md`

2. **Integration Approach:**

   - Add "Detailed Workflows from Helpdesk" section after "User Experience"
   - Extract step-by-step workflows from helpdesk articles
   - Include troubleshooting information where relevant
   - Enhance "Key Functionality" with specific details from helpdesk
   - Update UI component descriptions with helpdesk insights

3. **Workflow Format:**

   ```markdown
   ### Detailed Workflows from Helpdesk

   #### Workflow: [Workflow Name]

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

   **Steps:**

   1. [Step 1 description]
   2. [Step 2 description]
   3. [Step 3 description]
   ```

4. **Avoid Redundancy:**

   - Don't duplicate existing content
   - Focus on workflows and step-by-step guides
   - Extract unique information not already documented
   - Reference helpdesk articles for complete details

5. **Validation:**
   - Ensure workflows match actual system behavior
   - Verify technical details are accurate
   - Check that helpdesk content is current
   - Update "Last Updated" date after integration

**Related Documentation:**

- `docs/content/helpdesk/ENHANCEMENT_PLAN.md` - Enhancement planning guide
- `docs/content/helpdesk/FINAL_PROJECT_SUMMARY.md` - Final project summary with completed enhancements
- `docs/content/helpdesk/HELPDESK_TO_FEATURE_MAPPING.md` - Helpdesk to feature mapping

## Maintenance Requirements

### Update Triggers

Update feature documentation when:

- New features added to the product
- Product page content changes significantly
- API endpoints change
- User workflows change
- Technical implementation changes
- User feedback indicates gaps
- Helpdesk articles are updated or new ones added

### Update Process

1. Read existing documentation completely
2. Identify what needs updating
3. Check for new helpdesk content if updating workflows
4. Update content following standards
5. Update "Last Updated" date (use `date +%Y-%m-%d`)
6. Update cross-references if needed
7. Run validation script: `python3 scripts/documentation/validate-feature-docs.py`
8. Fix any broken links or warnings
9. Update `PRODUCT_FEATURES_INVENTORY.md` if status changed

### Regular Maintenance Schedule

- **Monthly:** Review for accuracy, update as needed
- **Quarterly:** Run validation scripts, fix broken links
- **Annually:** Comprehensive review, update all dates

## Common Pitfalls

### Placeholder Text

❌ **BAD:**

- "Use cases to be documented"
- "Technical implementation TBD"
- "Advanced features to be documented"

✅ **GOOD:**

- Complete, detailed descriptions
- Specific examples and scenarios
- Actual file paths and endpoints

### Vague Use Cases

❌ **BAD:**

- "Employees can clock in/out"
- "Managers can create schedules"

✅ **GOOD:**

- Detailed scenario with context
- Step-by-step process
- Specific, measurable benefits

### Missing Technical Details

❌ **BAD:**

- "Uses JavaScript and CSS"
- "Integrates with other systems"

✅ **GOOD:**

- Specific file paths: `v2/js/timetracking.js`
- Complete dependency lists
- API endpoint specifications

### Outdated Information

❌ **BAD:**

- Last Updated: 2024-01-01 (over 1 year old)
- References to old file paths
- Mentions of deprecated features

✅ **GOOD:**

- Current dates (check with `date +%Y-%m-%d`)
- Verified file paths
- Up-to-date feature descriptions

## Validation

### Automated Validation

Run validation script before committing:

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

**Checks:**

- All required sections present
- No placeholder text
- Last Updated date present and recent
- Links valid
- Cross-references present

### Manual Review Checklist

- [ ] Content accuracy verified
- [ ] Use cases are realistic and detailed
- [ ] Technical details match actual implementation
- [ ] User flows match actual workflows
- [ ] Visual documentation planned or existing
- [ ] Cross-references work correctly

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.

**Key Documentation:**

- [docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md](../../docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md) - Feature inventory
- [docs/content/product-features/ENHANCEMENT_SUMMARY.md](../../docs/content/product-features/ENHANCEMENT_SUMMARY.md) - Enhancement summary
- [docs/DOCUMENTATION_TEMPLATES.md](../../docs/DOCUMENTATION_TEMPLATES.md) - Documentation templates
- [docs/content/product-features/VISUAL_DOCUMENTATION_PLAN.md](../../docs/content/product-features/VISUAL_DOCUMENTATION_PLAN.md) - Visual documentation plan
- [docs/content/product-features/CONTENT_ENHANCEMENT_PLAN.md](../../docs/content/product-features/CONTENT_ENHANCEMENT_PLAN.md) - Content enhancement plan

## Related Cursor Rules

- [product-pages.mdc](product-pages.mdc) - Product page patterns (marketing pages)
- [shared-patterns.mdc](shared-patterns.mdc) - Universal copy guidelines
- [global.mdc](global.mdc) - Global planning and quality standards