57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
|
# docs/
|
||
|
|
|
||
|
|
Alle Dokumentation zur Electric-Horses-Infrastruktur. Jeder Unterordner hat seine eigene `README.md` mit Konventionen und Index.
|
||
|
|
|
||
|
|
## Struktur
|
||
|
|
|
||
|
|
```
|
||
|
|
docs/
|
||
|
|
├── README.md # diese Datei
|
||
|
|
│
|
||
|
|
├── architecture/ # Topologie, Stack-Inventories, Diagramme
|
||
|
|
│ └── ai-apps-stacks.md # Stack-Snapshot auf ai-apps
|
||
|
|
│
|
||
|
|
├── adr/ # Architecture Decision Records
|
||
|
|
│ ├── README.md # Format-Guide + Index
|
||
|
|
│ └── 0001-0006-*.md # 6 ADRs aus M7.1
|
||
|
|
│
|
||
|
|
├── runbooks/ # Schritt-für-Schritt Anleitungen für Ops
|
||
|
|
│ ├── README.md # Format + Index
|
||
|
|
│ ├── forgejo-admin-recovery.md
|
||
|
|
│ └── forgejo-backup-restore.md
|
||
|
|
│
|
||
|
|
└── guides/ # Wiederverwendbare Setup-Anleitungen
|
||
|
|
├── README.md # Format + Index
|
||
|
|
└── authentik-oauth2-provider.md
|
||
|
|
```
|
||
|
|
|
||
|
|
## Philosophie
|
||
|
|
|
||
|
|
**Docs-as-Code:** Dokumentation lebt neben dem Code, im selben Git-Repo, mit derselben Change-History. Keine separaten Wikis (driften), keine Confluence (teuer, closed), keine Notion (lock-in).
|
||
|
|
|
||
|
|
**Mermaid für Diagramme:** Forgejo rendert Mermaid-Blöcke im Web-UI direkt. Beispiel:
|
||
|
|
~~~mermaid
|
||
|
|
graph LR
|
||
|
|
Browser --> Nginx
|
||
|
|
Nginx --> Directus
|
||
|
|
Nginx --> Astro
|
||
|
|
~~~
|
||
|
|
|
||
|
|
**Markdown für alles andere:** Keine Word-Docs, keine PDFs (außer Anhänge). Alles in Plain-Text lesbar + commitbar + diffbar.
|
||
|
|
|
||
|
|
## Was hierher gehört
|
||
|
|
- Architektur-Beschreibungen, Topologie-Diagramme
|
||
|
|
- ADRs (warum haben wir X gebaut wie wir es gebaut haben)
|
||
|
|
- Runbooks (wie debuggt / repariert man konkret)
|
||
|
|
- Guides (wie richtet man etwas Wiederkehrendes ein)
|
||
|
|
- How-Tos für Team-Onboarding (später, wenn das Team wächst)
|
||
|
|
|
||
|
|
## Was NICHT hierher gehört
|
||
|
|
- Secrets / Credentials (niemals, Repo ist public!)
|
||
|
|
- Kundendaten / personenbezogene Daten (DSGVO)
|
||
|
|
- Marketing-Texte (gehört auf die Website)
|
||
|
|
- Lange Design-Specs in Rohform (lieber als ADR destillieren)
|
||
|
|
|
||
|
|
## Navigation-Tipp
|
||
|
|
Im Forgejo-Web-UI kannst du die `README.md`-Dateien durchklicken — jede erklärt ihren Unterordner und verlinkt die einzelnen Inhalte. Das ersetzt ein Wiki-Interface.
|