Technischer Workflow der Dokumentation

Dieses Diagramm veranschaulicht, wie das Dokumentationssystem von Daktela aus technischer Sicht funktioniert.

Quellen für die Erstellung der Dokumentation

flowchart TB
    subgraph TOP[" "]
        direction LR
        subgraph SOURCES["User Input"]
            CU[("**ClickUp**<br/>PRDs & Tickets")]
            GL[("**GitLab**<br/>Code & Commits")]
            FG[("**Figma**<br/>UI Designs")]
        end

        subgraph GENERATOR["Claude Code Aggregation"]
            GEN[Claude Code]
            AGG[Aggregate by<br/>ticket number]
            OUT[Generate markdown]
            GEN --> AGG --> OUT
        end
    end

    subgraph LOCAL["Human Review"]
        direction LR
        EDIT[Edit & review] --> PREVIEW[mkdocs serve] --> COMMIT[Commit] --> PUSH[Push to updates]
    end

    CU --> GEN
    GL --> GEN
    FG --> GEN
    OUT --> EDIT

    style CU fill:#7b68ee,color:#fff
    style GL fill:#fc6d26,color:#fff
    style FG fill:#a259ff,color:#fff
    style GEN fill:#1976d2,color:#fff
    style PUSH fill:#4caf50,color:#fff
    style TOP fill:none,stroke:none

Prüf- und Deployment-Pipeline

flowchart TB
    subgraph TOP[" "]
        direction LR
        subgraph LOCAL["👤 Local Development"]
            D[Push to updates branch]
        end

        subgraph REVIEW["🔍 Review Process"]
            E[Create Merge Request] --> F[Reviewer reviews]
            F --> G{Approved?}
            G -->|Yes| I[Merge into main]
            G -->|No| H[Request changes]
            H --> D
        end
    end

    subgraph BOTTOM[" "]
        direction LR
        subgraph CICD["⚙️ GitLab CI/CD"]
            J[Pipeline triggered] --> M[mkdocs build]
        end

        subgraph DEPLOY["🚀 Deployment"]
            O[rsync to server] --> Q[docs.daktela.com]
        end
    end

    D --> E
    I --> J
    M --> O

    style LOCAL fill:#e1f5fe
    style REVIEW fill:#fff3e0
    style CICD fill:#f3e5f5
    style DEPLOY fill:#e8f5e9
    style TOP fill:none,stroke:none
    style BOTTOM fill:none,stroke:none

Workflows zur Erstellung der Dokumentation

1. ClickUp-Workflow

PRDs und Funktionsspezifikationen werden in ClickUp mit Ticketnummern verwaltet.

Schritt	Aktion
1	ClickUp-Aufgabe mit Ticketnummer erstellen (z. B. Feature #123456)
2	Anforderungen, Spezifikationen und Kontext zur Aufgabenbeschreibung hinzufügen
3	Die Ticketnummer verknüpft alle zugehörigen Arbeiten systemübergreifend

Unterstützte Formate für Ticketnummern: - Aufgabenname: Feature #123456 - Benutzerdefiniertes Feld „Ticket Number“: 123456 - ClickUp Custom ID: PROJ-123

2. GitLab-Codebasis-Workflow

Code-Commits verweisen auf Ticketnummern, um Implementierungsdetails zu verknüpfen.

Schritt	Aktion
1	Entwickler implementieren die Funktion in der Codebasis
2	Commits enthalten eine Ticketreferenz: fix: update login flow #123456
3	Der Generator durchsucht Commits nach der Ticketnummer

3. Figma-Workflow

UI-/UX-Designs liefern visuelle Dokumentation und Screenshots.

Schritt	Aktion
1	Designer erstellen Mockups in Figma
2	Der Generator exportiert Screenshots mit dem Flag --export-screenshots
3	Die Bilder werden in die generierte Dokumentation eingebettet

4. Dokumentationsgenerator

Der Generator aggregiert alle Quellen zu einer Entwurfsdokumentation.

# Generate docs for ticket #123456
./generate_docs.py 123456 -p contact-centre -v 2025.2

# With Figma screenshots
./generate_docs.py 123456 -p contact-centre -t feature --export-screenshots

Erforderliche API-Tokens: - ClickUp: app.clickup.com/settings/apps - GitLab: gitlab.daktela.com/-/profile/personal_access_tokens - Figma: www.figma.com/settings (optional)

Komponentendetails

Lokale Entwicklung

Komponente	Beschreibung
MkDocs	Statischer Site-Generator für die Dokumentation
Material Theme	Modernes, responsives Dokumentationsthema
mkdocs serve	Lokaler Vorschauserver (http://localhost:8000)
Doc Generator	Aggregiert die Quellen aus ClickUp, GitLab und Figma

CI/CD-Pipeline

Phase	Aktion
Trigger	Push in den Branch main
Container	squidfunk/mkdocs-material:latest
Build	mkdocs build → Verzeichnis output/
Deploy	rsync -avzP --delete in die Produktion

Infrastruktur

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   ClickUp    │  │    GitLab    │  │    Figma     │
│  (PRDs &     │  │  (Commits &  │  │  (UI/UX      │
│   Tickets)   │  │   Code)      │  │   Designs)   │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └────────────────┬┴─────────────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  Doc Generator      │
              │  generate_docs.py   │
              └──────────┬──────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     GitLab Repository                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   updates   │───▶│    main     │───▶│  CI/CD      │     │
│  │   branch    │ MR │   branch    │    │  Pipeline   │     │
│  └─────────────┘    └─────────────┘    └──────┬──────┘     │
└──────────────────────────────────────────────│──────────────┘
                                               │
                                               ▼
                              ┌────────────────────────────────┐
                              │     Production Server          │
                              │  vmakestest.daktela.com        │
                              │  ┌──────────────────────────┐  │
                              │  │   /opt/doc/              │  │
                              │  │   ├── en/                │  │
                              │  │   ├── cs/                │  │
                              │  │   └── assets/            │  │
                              │  └──────────────────────────┘  │
                              └────────────────────────────────┘

Kurzreferenz

Lokale Vorschau:

mkdocs serve
# or using Docker:
docker run --rm -v "$(pwd):/docs" -p 8000:8000 squidfunk/mkdocs-material:latest serve -a 0.0.0.0:8000

Manueller Build:

./scripts/build-docs.sh

Wichtige Dateien: - mkdocs.yml – Haupt-MkDocs-Konfiguration - .gitlab-ci.yml – Definition der CI/CD-Pipeline - .doc-generator/ – Werkzeug des Dokumentationsgenerators - docs/ – Quelldokumentation (Markdown) - output/ – Erstellte Website (generiert)

End-to-End-Beispiel

1. PM creates ClickUp task: "Add dark mode toggle #789012"
2. Developer commits: "feat: implement dark mode #789012"
3. Designer uploads Figma mockups for dark mode UI
                            ↓
4. Run: ./generate_docs.py 789012 -p contact-centre --export-screenshots
                            ↓
5. Generator outputs draft markdown with:
   - Feature description from ClickUp PRD
   - Technical details from GitLab commits
   - Screenshots from Figma designs
                            ↓
6. Author reviews, edits, runs mkdocs serve
7. Push to updates branch → Merge Request
8. Reviewer approves → Merge to main
9. CI/CD builds & deploys to production