Better Doc
Überprüfen Sie Dokumente anhand zweier sich ergänzender Frameworks:
- Classical Style (Pinker) – Klarheit, Präzision, Notwendigkeit
- Smart Brevity (Axios) – Struktur, Scanbarkeit, Wirkung
Ziel: Text zu einem transparenten Fenster zur Bedeutung machen. Kürze ist Selbstvertrauen; Länge ist Angst.
Wichtige Regel: Das Wesentliche bewahren
Kürze ≠ Löschung. Vereinfachen Sie den Ausdruck, bewahren Sie die Bedeutung.
Wenn Sie vorhandene Dokumente (insbesondere Prompts) überprüfen:
| Tun | Nicht tun |
|---|---|
| Wortreiche Anforderungen direkter formulieren | Anforderungen löschen, die lang erscheinen |
| Wortreiche Erklärungen zusammenfassen | Kontext entfernen, den der Leser braucht |
| Vage Begriffe durch spezifische ersetzen | Einschränkungen oder Randfälle entfernen |
| Zur Klarheit umstrukturieren | Informationen beim Umstrukturieren verlieren |
Bevor Sie etwas streichen, fragen Sie sich:
- Vermittelt dies eine Anforderung, Einschränkung oder einen Kontext?
- Würde das Entfernen das Ergebnis verändern?
- Kann ich dasselbe mit weniger Wörtern sagen, anstatt zu löschen?
Speziell für Prompts:
- Anforderungen in Absätzen vergraben → Als explizite Aufzählungspunkte extrahieren
- Implizite Einschränkungen → Explizit machen, nicht als offensichtlich voraussetzen
- Wortreicher Kontext → Zusammenfassen, aber behalten, wenn er das Verhalten beeinflusst
- Beispiele → Behalten, wenn sie Randfälle klären, entfernen, wenn sie redundant sind
Falscher Ansatz: „Dieser Absatz ist lang, löschen Sie ihn.“ Richtiger Ansatz: „Dieser Absatz enthält 3 Anforderungen. Formulieren Sie sie als 3 Aufzählungspunkte um.“
Kernprinzipien
Classical Style (8 Prinzipien)
- Direkte Sprache – Aktiv, klare Akteure
- Nur notwendiger Inhalt – Entfernen, was das Verständnis nicht verbessert
- Keine künstliche Komplexität – Struktur dient der Klarheit, nicht der Dekoration
- Spezifisch vor abstrakt – Konkrete, überprüfbare Begriffe
- Einheitliche Terminologie – Ein Name pro Konzept
- Klare Absicht – Ziel, Einschränkungen, Ausgabeformat (für Prompts)
- Leser-zentrierte Reihenfolge – Abfolge folgt dem Verständnispfad
- Überprüfbare Behauptungen – Fakten und Logik, nicht Eindrücke
Smart Brevity (4 Komponenten)
- Starke Überschrift – 6 Wörter oder weniger, Aufmerksamkeit erregen
- Eine Kernbotschaft – Erster Satz = DAS EINE, woran man sich erinnern soll
- Warum es wichtig ist – Kontext zur Relevanz für den Leser
- Tiefer eintauchen – Optionale Details, aufgeteilt in Aufzählungspunkte
Ausführliche Erklärungen: references/principles.md
Überprüfungsworkflow
Schritt 1: Dokument klassifizieren
| Typ | Schwerpunkte |
|---|---|
| E-Mail/Update | Smart Brevity Struktur, Scanbarkeit |
| Prompt/Anweisung | Absichtsklarheit, Einschränkungen, Format |
| Technisches Dokument | Präzision, Terminologie, Hierarchie |
| Allgemeiner Text | Classical Style, Fluss, Notwendigkeit |
Schritt 2: Smart-Brevity-Struktur prüfen
Für E-Mails, Updates, Ankündigungen:
✓ Überschrift: ≤6 starke Wörter?
✓ Erster Satz: EINE Kernbotschaft?
✓ „Warum es wichtig ist“: Relevanz für den Leser klar?
✓ Details: Aufgelistet, scanbar?
✓ Fett: Schlüsselbegriffe hervorgehoben?
Schritt 3: Classical Style prüfen
| Prinzip | Warnsignale |
|---|---|
| Direkte Sprache | Passiv, Nominalisierungen, versteckte Verben |
| Notwendiger Inhalt | Füllwörter, Wiederholungen, offensichtliche Aussagen |
| Keine Komplexität | Überformatierung, verschachtelte Aufzählungen, unnötige Überschriften |
| Spezifisch | „verschiedene“, „Aspekte“, undefinierter Jargon |
| Einheitliche Begriffe | Gleiche Sache, andere Namen |
| Klare Absicht | Fehlendes Ziel, vage Einschränkungen |
| Leser-Reihenfolge | Themenwechsel, Schlussfolgerung vor Kontext |
| Überprüfbar | „Es scheint“, unbelegte Behauptungen |
Schritt 4: Wort-Ebene prüfen
Smart-Brevity-Wortregeln:
- Kurze Wörter gewinnen: 1 Silbe > 2 > 3
- Streichen: Adverbien, schwache Wörter, Füllwörter
- Immer aktive Verben
| Streichen | Behalten/Ersetzen |
|---|---|
| „Um zu“ | „Zu“ |
| „Aufgrund der Tatsache, dass“ | „Weil“ |
| „Zum jetzigen Zeitpunkt“ | „Jetzt“ |
| „Nutzen“/„Verwenden“ (lang) | „Nutzen“ (kurz) / „Benutzen“ |
| „Implementieren“ | „Machen“ / „Bauen“ |
| „Ermöglichen“ | „Helfen“ |
Schritt 5: Ergebnisse melden
## Überprüfungszusammenfassung
**Typ**: [E-Mail/Prompt/Technisch/Allgemein]
**Gesamt**: [Einzeilige Bewertung]
## Struktur (Smart Brevity)
- Überschrift: [✓/✗ + Korrektur]
- Erster Satz: [✓/✗ + Korrektur]
- Warum es wichtig ist: [✓/✗ + Korrektur]
- Scanbarkeit: [✓/✗ + Korrektur]
## Stil (Classical)
[Verstöße mit Ort, Problem und Korrektur auflisten]
## Vorgeschlagene Überarbeitung
[Verbesserte Version, falls gewünscht]
Kurzreferenz: Smart-Brevity-Format
Für E-Mails und Aktualisierungen diese Struktur verwenden:
**[6-Wort-Überschrift]**
[EIN Satz: die Kernbotschaft]
**Warum es wichtig ist**: [1-2 Sätze zur Relevanz für den Leser]
**Was als nächstes kommt** / **Tiefer eintauchen** / **Details**:
• [Aufzählungspunkt 1]
• [Aufzählungspunkt 2]
• [Aufzählungspunkt 3]
**Fazit**: [Optionale abschließende Kernbotschaft]
Prompt-spezifische Prüfungen
Zielstruktur:
Ziel: [Einzelne klare Aussage]
Einschränkungen:
- [Grenze 1]
- [Was NICHT zu tun ist]
- [Längen-/Formatgrenzen]
Ausgabeformat: [Exakte Struktur]
Bei der Verbesserung vorhandener Prompts:
| Ursprüngliches Problem | Korrektur (NICHT löschen) |
|---|---|
| Anforderung im Prosatext vergraben | Extrahieren → expliziter Aufzählungspunkt |
| Vage Einschränkung („sei vorsichtig“) | Spezifisch machen („niemals X überschreiten“) |
| Implizite Annahme | Explizit formulieren |
| Redundantes Beispiel | Nur entfernen, wenn ein anderes Beispiel es abdeckt |
| Lange Erklärung eines Randfalls | Zusammenfassen, die Regel beibehalten |
Checkliste vor der Fertigstellung:
- Alle ursprünglichen Anforderungen noch vorhanden?
- Einschränkungen expliziter als zuvor?
- Beim Umstrukturieren nichts verloren gegangen?
- Kürzer UND klarer (nicht nur kürzer)?
Markierung: Fehlendes Ziel, vage Begriffe („gut“, „angemessen“), kein Ausgabeformat.
Häufige Korrekturen
| Problem | Vorher | Nachher |
|---|---|---|
| Passiv | „Die Daten werden verarbeitet“ | „Das System verarbeitet Daten“ |
| Nominalisierung | „Eine Entscheidung treffen“ | „Entscheiden“ |
| Füllwort | „Es ist wichtig zu beachten“ | [löschen] |
| Langes Wort | „Nutzen“ (lang) | „Nutzen“ (kurz) |
| Vage | „Verschiedene Faktoren“ | „Kosten, Zeit, Umfang“ |
| Schwache Überschrift | „Update zum Projekt“ | „Projekt startet am Freitag“ |
| Vergrabener Lead | [Absatz vor dem Punkt] | [Punkt zuerst] |
Verwandte Fähigkeiten
Teil einer kleinen Familie offener Agent-Fähigkeiten für vertrauenswürdige, klare Kommunikation:
- reduce-hallucination – LLM-Agenten prüfen; fundieren, zitieren, enthalten.
- better-doc – Classical Style + Smart Brevity.
- numbers – Zahlen bedeutungsvoll machen und sauber darstellen.