README Engineering & Leitfaden für Technische Dokumentation
Ein strenger Rahmen für die Erstellung erstklassiger, menschenlesbarer GitHub-Repository-READMEs, die die Zeit des Lesers respektieren, technischen Wert klar kommunizieren und generisches Marketing-Gefüller eliminieren.
1. Die Kernphilosophie: Die 30-Sekunden-Regel
Entwickler und Benutzer "lesen" keine Dokumentation von Anfang bis Ende – sie überfliegen sie mit hoher Geschwindigkeit. Versetzen Sie sich in die Lage eines müden Entwicklers, der um 2 Uhr morgens zufällig auf Ihr Repository stößt.
Ihr README muss drei Fragen in unter 30 Sekunden beantworten:
- Was ist das? (Eine klare, ein-sätzige Definition ohne Marketing-Gefüller).
- Warum sollte mich das interessieren? (Das reale Problem, das es löst, und welche frustrierenden Workarounds es ersetzt).
- Wie führe ich es sofort aus? (Eine 3-Schritte-, kopierbare Schnellstartanleitung mit getesteten Befehlen).
2. Richtlinien für klares, bodenständiges Schreiben
Dokumentation verfällt oft in aufgeblasene Unternehmens-PR-Sprache. Hochwertige Open-Source-Projekte vermeiden diesen Ton vollständig.
2.1 Das Wörterbuch der verbotenen Wörter & Klischees
| ❌ Verbotenes Schlagwort / Klischee | ✔️ Klare, bodenständige Alternative |
|---|---|
| "In der heutigen schnelllebigen digitalen Landschaft..." | (Löschen. Kommen Sie direkt zum Problem). |
| "Mühelos übertragen / nahtlos integrieren..." | "Ziehen Sie Dateien aus Ihrem Browser und sie erscheinen auf Ihrem Telefon." |
| "Eine revolutionäre, hochmoderne Plattform..." | "Ein leichtgewichtiger, selbst gehosteter persönlicher Relay." |
| "Steigert Ihre Produktivität auf neue Höhen..." | "Erspart Ihnen, sich selbst Links zu mailen." |
| "Ein Zeugnis moderner Entwicklung..." | (Löschen. Sprechen Sie wie ein Entwickler, nicht wie eine PR-Agentur). |
| "Riesige Heldenbanner vollständig eliminiert..." | (Prahlen Sie niemals mit internen Refactorings. Geben Sie an, was die UI jetzt bietet). |
| "Architektur für defensives Web-Sign-In..." | "Sicherer Login mit HttpOnly-SameSite-Cookies und CSRF-Tokens." |
| "Zero-Skeleton-SWR-Cache..." | "Sofortiger Ladevorgang: Öffnet Ihren Posteingang ohne weiße Leerseiten." |
2.2 Regeln für authentisches Schreiben
- Der "Dienstag-Morgen-Kaffee"-Test: Lesen Sie Ihren Entwurf laut vor. Klingt es wie ein nachdenklicher Softwareentwickler, der einem Kollegen bei einer Tasse Kaffee sein Lieblingswerkzeug erklärt? Wenn es wie eine Unternehmensmarketing-Broschüre klingt, schreiben Sie es um.
- Badge-Disziplin: Beschränken Sie Badges auf 3–6 aussagekräftige Indikatoren (Release, Build/CI-Status, Lizenz, Haupt-Stack). Stapeln Sie keine 15 dekorativen Shields, die vom Projekt ablenken.
- Keine mysteriösen Voraussetzungen: Schreiben Sie niemals
docker compose upodernpm start, ohne die Voraussetzungen und die Herkunft der Umgebungsanmeldeinformationen aufzulisten.
3. Die Struktur für zwei Zielgruppen
Großartige Dokumentation überbrückt zwei unterschiedliche Zielgruppen, ohne die Klarheit zu beeinträchtigen:
flowchart TD
Audience["Repository-Besucher"]
Audience --> HomeUser["1. Normalperson / Alltagsbenutzer<br>(Möchte wissen, ob dies sein Problem löst)"]
Audience --> Sysadmin["2. Entwickler / Systemadministrator / Entwickler<br>(Möchte die Architektur, Sicherheit und den Stack kennen)"]
HomeUser --> PlainSection["Abschnitt 'Warum gibt es das?'<br>- Reale Situationen (keine SMS-Bots oder E-Mail-Anhänge mehr)<br>- 3-Schritte-Konzeptablauf<br>- Vorteile von Datenschutz & Selbsthosting"]
Sysadmin --> TechSection["Abschnitt 'Wie es funktioniert'<br>- Architekturdiagramm (Mermaid)<br>- Verantwortlichkeiten der Komponenten<br>- Sicherheits- & Token-Modell<br>- Speicher- & Datenbankmechanik"]
3.1 Einfache Sprache für alltägliche Benutzer
Beginnen Sie mit nachvollziehbaren, realen Problemen:
"Haben Sie sich schon einmal selbst einen Link gemailt, einem Bot auf Telegram oder WhatsApp geschrieben, nur um Text auf Ihr Telefon zu kopieren, oder auf die Cloud-Sync gewartet, nur um eine einzelne PDF zu verschieben? Vault ersetzt diese Workarounds mit Ihrer eigenen privaten Drop-Box."
3.2 Bodenständige technische Tiefe für Entwickler
Fahren Sie mit präzisen Architektur- und Implementierungsdetails fort:
- API-Engine: ASP.NET Core 10 Minimal APIs streamt Dateien bis zu 100 MB direkt auf die Festplatte mit SHA-256-Verifizierung in Echtzeit (null RAM-Aufblähung).
- Web SPA: React 19 + TypeScript mit SameSite-HttpOnly-Cookies, CSRF-Tokens und Tastaturkürzeln (
/Suche). - Mobiler Client: Nativer Kotlin Jetpack Compose mit WorkManager-Offline-Outbox-Warteschlangen und Android
FileProvider-Integration. - Datenbank: PostgreSQL 18 speichert Metadaten und 14-Tage-Sliding-Session-Tokens.
4. Visuelle Präsentationen & UI-Layouts
Wenn Ihre Anwendung eine visuelle Oberfläche hat (Web, Mobil oder CLI-Ausgabe), zeigen Sie sie sofort nach der Einführungspräsentation.
4.1 Reaktives Präsentationstabellenmuster
<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 Mobil-Posteingang</th>
<th width="33%" align="center">⚙️ Geräte-Hub</th>
<th width="34%" align="center">🔐 Nahtloses Pairing</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="Mobil-Posteingang" width="260px" />
<br/>
<sub><i>Sofortiger lokaler Cache, Live-Suche und Ein-Klick-Aktionen.</i></sub>
</td>
<!-- Restliche Spalten -->
</tr>
</table>
4.2 Screenshot-Regeln:
- Aussagekräftige Bildunterschriften: Verwenden Sie Bildunterschriften, um zu beschreiben, was der Benutzer in der Ansicht tun kann, nicht um Schlagwörter aneinanderzureihen.
- Echte Screenshots: Verwenden Sie immer gestochen scharfe Aufnahmen der tatsächlichen Produkt-UI anstelle von generischen Mockup-Vorlagen mit falschen Laptop-Rahmen.
5. Durchdachtes Schnellstart-Design
Schnellstarts müssen ohne Fehlersuche reproduzierbar sein.
Der Standard-Drei-Schritte-Aufbau:
### 1. Lokale Zertifikate & Anmeldeinformationen generieren
```bash
./scripts/setup-local.sh # oder ./scripts/setup-local.ps1
Was das tut: Generiert ein vertrauenswürdiges Localhost-TLS-Zertifikat in .local/tls/ und schreibt ein zufälliges Bootstrap-Passwort in .env.
2. Den Stack starten
docker compose up -d
3. Ihren Arbeitsbereich öffnen
Navigieren Sie in Ihrem Browser zu https://localhost:8080:
- Benutzername:
[email protected](oderowner) - Passwort: Das Bootstrap-Passwort in Ihrer
.env-Datei
---
## 6. Standard-README-Struktur-Checkliste
Verwenden Sie diese Checkliste bei der Strukturierung des README eines technischen Repositorys:
- [ ] **1. Kopfzeile & Titel:** Logo/Symbol, Titel und ein ein-sätziger, funktionaler Slogan.
- [ ] **2. Fokussierte Badges:** Release-Version, Build-Status, Kernplattformen, Lizenz.
- [ ] **3. Warum es das gibt:** Das alltägliche Problem, die Lösung und der 3-Schritte-Ablauf in einfacher Sprache.
- [ ] **4. Visuelle Tour:** Screenshots der Web-, Mobil- oder CLI-Oberflächen mit praktischen Bildunterschriften.
- [ ] **5. Kernfunktionen:** Benutzerzentrierte Funktionsliste, organisiert nach tatsächlichen Aufgaben.
- [ ] **6. Wie es funktioniert (Technisch):** Mermaid-Architekturdiagramm + präzise Komponentenaufschlüsselung (API, Client, DB, Auth/Sicherheit).
- [ ] **7. Schnellstart (Docker / Lokal):** Voraussetzungen, Schritt-für-Schritt-Befehle und Speicherorte der Anmeldeinformationen.
- [ ] **8. Mobil-/Client-Setup (falls zutreffend):** Direkte Download-Links, Pairing-Anweisungen und LAN-Testanleitung.
- [ ] **9. Automatisierte Tests & Überprüfung:** Befehle zum lokalen Ausführen von Backend- und Frontend-Testsuiten.
- [ ] **10. Repository-Karte & Mitwirken:** Saubere ASCII-Ordnerstruktur, Link zu den Richtlinien und MIT/Apache-Lizenz.
---
## 7. Referenz-Open-Source-Repositories
Untersuchen Sie diese gefeierten Open-Source-READMEs für strukturelle und visuelle Inspiration:
- **`matiassingers/awesome-readme`**: Kuratierte Sammlung der besten READMEs auf GitHub.
- **`othneildrew/Best-README-Template`**: Der Branchen-Goldstandard für modulare, wirkungsvolle Repository-Vorlagen.
- **`charmbracelet/bubbletea` & `charmbracelet/gum`**: Herausragende Terminal-Präsentationen, GIF-Nutzung und überfliegbare Code-Blöcke.
- **`supabase/supabase`**: Hervorragende Balance für zwei Zielgruppen mit klaren Systemarchitekturdiagrammen und schnellem Onboarding.
- **`fastapi/fastapi`**: Meisterklasse für reibungslose Schnellstarts, echte Code-Beispiele und klare Wertversprechen.