# Partner Resource Tagging Guide

**Last Updated:** 2026-02-05

## Overview

This guide explains the standardized tagging and product classification system for partner marketing assets in the Resources Library.

## Problem Statement

Previously, the tagging system had several issues:

1. **Too many single-use tags** - Tags were created for individual words appearing once in an image
2. **Redundant product names** - Multiple variations like "Dienstplan", "Dienstplan Software", "Dienstplan-Software"
3. **Inconsistent naming** - Case variations, different terms for same concept
4. **Lack of context** - Tags didn't consider the overall visual message

## Solution: Standardized Taxonomy

### Products (Standardized List)

Products represent core Ordio features/modules. Use **only** these standardized names:

- **Schichtplanung** (covers: Dienstplan, Schichtplan, Dienstplanung, etc.)
- **Zeiterfassung** (covers: Arbeitszeiterfassung, Zeiterfassung)
- **Lohnabrechnung** (covers: Payroll, Lohn & Gehalt)
- **Abwesenheitsmanagement** (covers: Urlaubsplanung, Abwesenheiten)
- **Checklisten**
- **Dokumentenmanagement**
- **Digitale Personalakte**
- **Warenbestellung**
- **Mobile App** (covers: App, Web App, App & Web)
- **GPS Tracking**
- **Reporting & Auswertung**

**Rules:**
- Maximum 3-4 products per resource
- Only include products that are **prominently featured** in the visual
- Consider the **overall message**, not just individual words
- Use normalization map for variations (see `tag-taxonomy.json`)

### Tags (Categorized System)

Tags help users find similar assets. Use broad, reusable categories.

**Tag Categories:**

1. **Content Type** (optional - only if relevant):
   - Dashboard
   - Mobile App
   - Banner
   - Social Media
   - Video
   - Customer Spotlight

2. **Visual Style** (optional - only if relevant):
   - Infographic
   - Illustration
   - UI/UX
   - Mockup

3. **Use Case** (only if clearly identifiable):
   - Gastronomie
   - Einzelhandel
   - Handwerk
   - Gesundheitswesen
   - Freizeit & Kultur
   - Schichtbetrieb
   - Multi-Location

4. **Feature Highlight** (only if main theme):
   - GPS Tracking
   - Reporting
   - Automatisierung
   - Integration
   - Team Management
   - Compliance

5. **Marketing** (only for marketing assets):
   - Partner
   - Sales
   - Präsentation
   - Pitch Deck

**Rules:**
- Maximum 5-6 tags per resource
- Focus on tags that help users find **similar assets**
- Avoid single-use tags - use broader categories
- Consider: **What would a partner search for to find this asset?**
- Tags should represent the **overall visual theme**, not individual words
- Group similar concepts (e.g., "Schichtbetrieb" covers "Schichtbetriebe")

**Blacklisted Tags:**
- "Image", "Bild", "Asset" (too generic)
- "Screenshot" (only use if specifically a screenshot-focused asset)

## Implementation

### Analysis Script (`analyze-assets.py`)

The script uses an improved Gemini prompt that:
- Provides standardized product list
- Explains tag categories and rules
- Emphasizes overall visual context over individual words
- Limits products (1-4) and tags (3-6)

Post-processing normalizes:
- Products using normalization map
- Tags using blacklist
- Case-insensitive matching
- Duplicate removal

### Cleanup Script (`cleanup-resource-tags.php`)

Use this script to clean up existing resources:

```bash
# Dry run (preview changes)
php v2/scripts/partner/cleanup-resource-tags.php --dry-run

# Apply changes with backup
php v2/scripts/partner/cleanup-resource-tags.php --backup

# Apply changes without backup
php v2/scripts/partner/cleanup-resource-tags.php
```

The script:
- Normalizes all products using taxonomy
- Removes blacklisted tags
- Limits products to 4 max, tags to 6 max
- Removes duplicates
- Updates timestamps

### Taxonomy File (`tag-taxonomy.json`)

Contains:
- Standardized product list
- Product normalization map
- Tag categories
- Tag blacklist
- Rules and guidelines

## Best Practices

### When Analyzing New Assets

1. **Look at the overall visual** - What is the main message?
2. **Identify primary products** - Which Ordio features are prominently shown?
3. **Choose broad tags** - What categories would help find similar assets?
4. **Avoid word-by-word tagging** - Don't tag every word that appears
5. **Consider use cases** - Who would use this asset? What industry?

### Examples

**Good Tagging:**
- Products: `["Schichtplanung", "Zeiterfassung"]`
- Tags: `["Dashboard", "Gastronomie", "Schichtbetrieb"]`
- Reason: Broad categories, reusable, helps find similar assets

**Bad Tagging:**
- Products: `["Dienstplan", "Dienstplan Software", "Dienstplan-Software"]`
- Tags: `["Screenshot", "Software", "Image", "Dashboard", "Mitarbeiter", "Planung", "Schicht"]`
- Reason: Redundant products, too many single-word tags, generic terms

## Maintenance

### Updating Taxonomy

1. Edit `v2/scripts/partner/tag-taxonomy.json`
2. Add new products to standardized list (if new feature)
3. Add normalization rules for variations
4. Update tag categories if needed
5. Run cleanup script to apply changes

### Adding New Assets

1. Place asset in `v2/img/partner/assets/`
2. Run analysis script:
   ```bash
   python3 v2/scripts/partner/analyze-assets.py
   ```
3. Review generated tags/products
4. Manually adjust if needed (following taxonomy)
5. Re-run cleanup script if manual changes made

### Re-analyzing for German Titles/Descriptions

All analysis output is in German. Titles and descriptions must be descriptive (no "Screenshot", "Image", "Marketing image", etc.). To re-analyze existing images with the current prompt:

```bash
python3 v2/scripts/partner/analyze-assets.py --force --delay 1.5
```

If the API rate limit (429) is hit, some entries may be missing; restore them from the latest backup in `v2/data/` then re-run the script later for those files only (e.g. with `--limit` and temporary move of other images).

## Related Files

- `v2/scripts/partner/analyze-assets.py` - Image analysis script
- `v2/scripts/partner/cleanup-resource-tags.php` - Cleanup script
- `v2/scripts/partner/tag-taxonomy.json` - Taxonomy definition
- `v2/data/partner_resources.json` - Resource data file
- `docs/systems/affiliate/RESOURCES_LIBRARY.md` - Resources library documentation