Schreiben mit KI
Erfahren Sie, wie Sie Dokumentation mit KI-Tools wie Claude Code, Cursor und Codex schreiben und prüfen, inklusive Prompt-Mustern und häufiger MDX-Fehler
Diese Strategien funktionieren mit jedem KI-Tool, einschließlich Claude Code, Cursor, Codex und Copilot. Die toolspezifische Einrichtung finden Sie unter Claude Code, Cursor oder Codex.
Warum MDX gut mit KI funktioniert
MDX ist eines der einfachsten Formate, die KI-Tools schreiben können:
- Vertraute Syntax: KI-Modelle wurden mit Millionen von Markdown-Dateien trainiert. Sie erzeugen gültiges MDX mit wenig Prompting.
- Strukturierte Komponenten:
<Card>,<Steps>und<Tabs>folgen vorhersehbaren Mustern, die Modelle schnell lernen. - Klartext: MDX besitzt keine Binärformate, proprietären Schemata oder Build-Artefakte, die ein KI-Tool interpretieren müsste.
Bessere Prompts schreiben
Der Prompt entscheidet meist darüber, ob KI-Dokumentation mittelmäßig oder gut wird. Seien Sie präzise, was Sie wollen.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Diese Prompts erzeugen generische, aufgeblähte Ausgaben. Die KI hat keine Vorgaben.
Funktionierende Prompt-Muster
| Muster | Beispiel |
|---|---|
| Leser festlegen | „Der Leser ist ein Backend-Entwickler, der unsere API noch nie verwendet hat“ |
| Struktur benennen | „Verwende Steps für den Setup-Ablauf, dann Tabs für Sprachvarianten“ |
| Längenbegrenzungen setzen | „Halte die Einleitung unter 2 Sätzen“ oder „Jede Accordion-Antwort sollte 3–4 Zeilen lang sein“ |
| Auf Quellcode verweisen | „Referenziere die Implementierung in /src/auth für Genauigkeit“ |
| Angeben, was wegzulassen ist | „Erkläre nicht, was REST ist. Lass die Theorie weg.“ |
| Eine Beispielseite geben | „Passe Ton und Struktur an /quickstart an“ |
KI-Ausgaben prüfen
KI-Tools erzeugen meist strukturell korrektes MDX. Die subtileren Probleme liegen in Ton, Genauigkeit und Aufblähung. Gehen Sie diese Checkliste durch, bevor Sie committen.
Sprachstil prüfen
Lesen Sie die Ausgabe laut vor. Wenn sie wie ein Chatbot klingt, schreiben Sie sie um. Achten Sie auf:
- Füllphrasen: „Es ist wichtig zu beachten, dass“, „Dies ermöglicht Ihnen“, „Um zu“
- Relativierungen: „Sie sollten eventuell in Betracht ziehen“, „Es wird im Allgemeinen empfohlen“
- Leere Übergänge: „Nachdem wir X behandelt haben, kommen wir nun zu Y“
- Schlagworte: „nahtlos“, „robust“, „nutzen“, „optimieren“
Streichen Sie diese.
Genauigkeit prüfen
KI-Tools liefern selbstbewusst falsche Informationen. Prüfen Sie:
- Funktionieren die Codebeispiele tatsächlich? Kopieren Sie sie und führen Sie sie aus.
- Sind die Konfigurationsoptionen real? Gegen den Quellcode prüfen.
- Sind die Komponentennamen korrekt? Verwenden Sie nur Komponenten, die existieren.
- Beschreibt die Seite das aktuelle Verhalten, nicht angestrebte Funktionen?
Struktur prüfen
- Frontmatter enthält sowohl
titleals auchdescription - Es gibt einen einleitenden Absatz ohne Überschrift davor
- Die Seite endet mit „Wie geht es weiter?“-Karten in einem
<Columns>-Wrapper - Neue Seiten sind in der
docs.json-Navigation ergänzt - Keine erfundenen Komponenten; nur die aus der Komponentenreferenz
Häufige Fehler von KI
KI-Tools erzeugen <CodeBlock>, <Alert>, <Section>, <Callout> und andere Komponenten, die es in Jamdesk nicht gibt. Verwenden Sie nur die Komponenten aus der Übersicht.
Eine Seite anzulegen, ohne sie zu docs.json hinzuzufügen, ist der häufigste Fehler. Die Seite existiert, erscheint aber nicht in der Seitenleiste. Ergänzen Sie jede neue Seite in der Navigation.
KI-Tools packen gern jeden zweiten Absatz in ein <Note> oder <Warning>. Ein oder zwei Hinweisboxen pro Seite reichen völlig.
Eine 200-zeilige Seite von der KI hat meist nur 100 Zeilen echten Inhalt. Achten Sie auf wiederholte Erklärungen, unnötigen Hintergrund und Absätze, die dasselbe mit anderen Worten sagen. Kürzen Sie rigoros.
„Diese leistungsstarke Funktion ermöglicht es Ihnen, …“ sagt dem Leser nichts. Sagen Sie, was sie tut: „Sendet HTTP-POST-Anfragen an Ihren Endpunkt, wenn Ereignisse auftreten.“
Dokumentation synchron halten
Dokumentation schreiben ist der einfache Teil. Sie aktuell zu halten, wenn sich der Code ändert, ist schwieriger.
Prompten Sie Ihr KI-Tool nach dem Ausliefern einer Funktion:
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.Seitengerüst
Verwenden Sie dies als Start-Prompt, wenn Sie die KI bitten, eine neue Seite zu erstellen:
Eine Jamdesk-Dokumentationsseite erstellen
Die obige Karte kopiert die vollständigen Anweisungen und das Skelett. Fügen Sie dieselbe Komponente mit diesem Quelltext zu Ihren Seiten hinzu:
<Prompt title="Create a Jamdesk documentation page" actions={["cursor", "claude", "chatgpt"]}>
Create a Jamdesk documentation page using this structure. Replace each
placeholder with specific, accurate content for the feature I describe.
```mdx
---
title: Feature Name
description: One sentence summarizing what this page covers.
---
Opening paragraph: what problem this solves and who should read this.
## Quick Start
<Steps>
<Step title="First step">What to do.</Step>
<Step title="Second step">What to do next.</Step>
</Steps>
## How It Works
Explain the mechanics. Use code examples.
## What's Next?
<Columns cols={2}>
<Card title="Related Page" icon="arrow-right" href="/path">
Why the reader would go here next
</Card>
</Columns>
```
</Prompt>