Technischer Workflow der Dokumentation¶

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

Quellen für die Erstellung der Dokumentation¶

![Quellen für die Erstellung der Dokumentation diagram](images/quellen-f-r-die-erstellung-der-dokumentation.svg){ .diagram-img }

Prüf- und Deployment-Pipeline¶

![Prüf- und Deployment-Pipeline diagram](images/pr-f-und-deployment-pipeline.svg){ .diagram-img }

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