openclaw-docs

OpenClaw-Dokumentation

Überblick

Verwenden Sie diesen Skill, wenn Sie OpenClaw-Entwicklerdokumentation für APIs, SDKs, CLI-Tools, Integrationen, Schnellstartanleitungen, Plattformhandbücher oder technische Produktdokumente schreiben, bearbeiten oder überprüfen.

Schreiben Sie Dokumentation, die präzise, hilfreich und umfassend ist: schnell zum ersten Erfolg, genau für die Produktion und beim Debuggen leicht überfliegbar.

Kernmodell

Verwenden Sie ein OpenClaw-Dokumentationsmodell, das durch die Prinzipien von "Write the Docs" gestärkt wird:

• Führen Sie mit dem, was der Entwickler erreichen möchte.
• Geben Sie einen empfohlenen Weg, bevor Sie Alternativen anbieten.
• Halten Sie Beispiele ausführbar und realistisch.
• Gestalten Sie Anleitungen aufgabenorientiert und Referenzen erschöpfend.
• Erklären Sie Produktionsrisiken genau dort, wo Entwickler Fehler machen können.
• Verknüpfen Sie Konzepte, Anleitungen, API-Referenzen, SDKs, Tests und Fehlerbehebungen, sodass Leser zwischen ihnen wechseln können, ohne erneut lesen zu müssen.
• Behandeln Sie Dokumentation als Teil des Produktlebenszyklus: Entwerfen Sie sie vor oder parallel zur Implementierung, überprüfen Sie sie mit dem Code und halten Sie sie aktuell.
• Gestalten Sie jede Seite auffindbar, adressierbar, kumulativ, vollständig in ihrem festgelegten Umfang und leicht überfliegbar.

Struktur

Wählen Sie den Seitentyp, bevor Sie schreiben:

• Überblick: Leiten Sie die Leser zum richtigen Produkt, Integrationspfad oder Leitfaden.
• Schnellstart: Bringen Sie einen neuen Benutzer mit den wenigsten sicheren Schritten zu einem funktionierenden Ergebnis.
• Themenseite: Geben Sie einen End-to-End-Überblick über eine wichtige Domänenentität mit Einrichtung, wichtigsten Unterthemen, Fehlerbehebung und Links zu tiefergehenden Referenzen.
• Anleitung: Erklären Sie einen Workflow von den Voraussetzungen bis zur Produktionsreife.
• API-Referenz: Definieren Sie jedes Objekt, jeden Endpunkt, Parameter, Enum, jede Antwort, jeden Fehler und jede Versionsregel.
• SDK- oder CLI-Referenz: Dokumentieren Sie Installation, Authentifizierung, Befehle oder Methoden, Optionen, Beispiele und Fehlermodi.
• Testanleitung: Zeigen Sie Sandbox-Einrichtung, Fixtures, Testdaten, simulierte Fehler und Unterschiede im Live-Modus.
• Anleitung zur Fehlerbehebung: Ordnen Sie Symptome Prüfungen, Ursachen und Behebungen zu.

Verwenden Sie diese Standard-Themenseitenstruktur:

1. Titel: Benennen Sie die Hauptentität oder -oberfläche.
2. Einleitender Überblick: Beginnen Sie mit einigen wenigen Sätzen ohne Überschrift, die erklären, was es ist, was es abdeckt und was nicht. Fügen Sie keine ## Überblick-Überschrift hinzu, es sei denn, die Seite selbst ist ein Überblicksindex.
3. Voraussetzungen: Nur dann einschließen, wenn die Einrichtung spezifische Konten, Versionen, Berechtigungen, Plugins, Betriebssysteme oder Anmeldeinformationen benötigt.
4. Schnellstart: Zeigen Sie den empfohlenen Einrichtungspfad und die kleinste zuverlässige Überprüfung.
5. Konfiguration: Zeigen Sie die Mindestkonfiguration, die zur Nutzung der Oberfläche erforderlich ist, häufige Varianten zwischen denen Benutzer wählen müssen und wo jede Option festgelegt wird: CLI, Konfigurationsdatei, Umgebungsvariable, Plugin-Manifest, Dashboard oder API.
6. Wichtige Unterthemen: Organisieren Sie die Hauptkonzepte, Workflows und Entscheidungen der Entität nach der Absicht des Lesers. Setzen Sie jedes wichtige Unterthema unter eine eigene Überschrift; packen Sie sie nicht in einen generischen Abschnitt ## Unterthemen.
7. Fehlerbehebung: Diagnostizieren Sie häufige beobachtbare Fehler unter einer expliziten ## Fehlerbehebung-Überschrift.
8. Verwandtes: Verlinken Sie zu Anleitungen, Referenzen, Befehlen, Konzepten und benachbarten Themen.

Themenseiten können länger sein als Schnellstarts, sollten aber keine erschöpfenden Referenzen werden. Verschieben Sie Feldtabellen, API-Verträge, enge Interna, Legacy-Details und seltene Debugging-Workflows auf verlinkte Referenz- oder Fehlerbehebungsseiten, wenn sie den End-to-End-Überblick unterbrechen.

Für die Konfiguration halten Sie aufgabenkritische Optionen inline. Verlinken Sie zu Referenzdokumenten für vollständige Optionslisten, Standardwerte, Enums, generierte Schemata und erweiterte Einstellungen. Verdoppeln Sie keine erschöpfenden Konfigurations-Referenztabellen auf Themenseiten, es sei denn, die Themenseite selbst ist die Referenz.

Verwenden Sie diese Standard-Anleitungsstruktur:

1. Titel: Benennen Sie das Ergebnis, nicht das Implementierungsdetail.
2. Einleitung: Geben Sie in ein oder zwei Sätzen an, was der Leser erreichen kann.
3. Bevor Sie beginnen: Listen Sie Konten, Schlüssel, Berechtigungen, Versionen, Tools und Annahmen auf.
4. Einen Weg wählen: Vergleichen Sie Optionen nur dann, wenn der Leser eine Entscheidung treffen muss.
5. Schritte: Verwenden Sie verbgeführte Überschriften mit Code, erwarteter Ausgabe und Prüfungen.
6. Testen: Zeigen Sie den kleinsten zuverlässigen Nachweis, dass die Integration funktioniert.
7. Produktionsreife: Behandeln Sie Sicherheit, Idempotenz, Wiederholungen, Limits, Beobachtbarkeit, Migrationen und Bereinigung.
8. Fehlerbehebung: Fügen Sie häufige Fehler in der Nähe des Workflows ein, der sie verursacht.
9. Siehe auch: Verlinken Sie zu Konzepten, API-Referenzen, SDK-Dokumentationen und angrenzenden Anleitungen.

Halten Sie die Navigation benutzerabsichtsorientiert. Zwingen Sie Leser nicht, die interne Produkttaxonomie zu verstehen, bevor sie eine Aufgabe auswählen können.

Dokumentationslebenszyklus

Schreiben und pflegen Sie Dokumentation mit derselben Disziplin wie Code:

• Entwerfen Sie Dokumente früh genug, um unklares Produkt-, API-, CLI- oder Konfigurationsdesign aufzudecken.
• Halten Sie die Dokumentationsquelle in der Nähe des Codes, der Konfiguration, des Befehls, des Plugins oder des Protokolls, das sie beschreibt, wenn es das Repository-Layout erlaubt.
• Vermeiden Sie doppelte Wahrheiten. Wenn derselbe Vertrag an mehreren Stellen erscheint, wählen Sie die kanonische Seite und verlinken Sie darauf.
• Aktualisieren Sie die Dokumentation in derselben Änderung wie Verhaltens-, Konfigurations-, API-, CLI-, Plugin- oder Fehlerbehebungsänderungen.
• Entfernen, leiten Sie weiter oder markieren Sie veraltete Dokumente klar. Falsche Dokumentation ist schlimmer als fehlende.
• Beziehen Sie die richtigen Reviewer ein: Code-Besitzer für das Verhalten, Support oder QA für Benutzerfehlermodi und Docs-Maintainer für Struktur und Stil.
• Bewahren Sie Anleitungen für ältere Versionen nur dann auf, wenn Benutzer sie benötigen; dokumentieren Sie andernfalls das aktuell unterstützte Verhalten.

Verwenden Sie FAQs nicht als Sammelbecken für unzusammenhängendes Material. Fördern Sie wiederkehrende Fragen auf Aufgaben-, Konzept-, Fehlerbehebungs- oder Referenzseiten.

Schreibstil

Schreiben Sie in einer direkten, praktischen Stimme:

• Verwenden Sie Präsens und aktive Stimme.
• Sprechen Sie den Leser mit "Sie" an, wenn Sie Anweisungen geben.
• Bevorzugen Sie kurze Absätze und überfliegbare Listen.
• Verwenden Sie konkrete Substantive: "Agentenprofil", "Gateway-Webhook", "Plugin-Manifest", "Sitzungszustand".
• Setzen Sie Warnhinweise genau dort, wo sie den Schritt betreffen.
• Vermeiden Sie Marketing-Sprache, Übertreibungen, allgemeine Vorteile und vage Behauptungen.
• Vermeiden Sie lange konzeptionelle Einleitungen vor dem ersten umsetzbaren Schritt.
• Erklären Sie gängige Entwicklungskonzepte nicht übermäßig, es sei denn, das Produkt hat einen ungewöhnlichen Vertrag.
• Definieren Sie OpenClaw-spezifischen Jargon und Abkürzungen vor der ersten Verwendung.
• Verwenden Sie Satzfall für Überschriften, es sei denn, ein OpenClaw-Produktname, ein Befehl oder eine Kennung erfordert Großschreibung.
• Verwenden Sie beschreibenden Linktext, der das Ziel oder die Aktion nennt; vermeiden Sie vage Links wie "diese Seite" oder "hier klicken".
• Vermeiden Sie kulturspezifische Redewendungen, gewalttätige Redewendungen und Witze, die die Übersetzung oder das Überfliegen der Dokumentation erschweren.
• Schreiben Sie zugängliche Prosa: Verlassen Sie sich nicht ausschließlich auf Farbe, Screenshots oder visuelle Positionen, um eine Anweisung zu vermitteln.

Verwenden Sie Überschriften, die Aktionen oder Referenzoberflächen beschreiben:

• Gut: "Einen Agenten erstellen", "Einen Slack-Kanal konfigurieren", "Plugin-Installation reparieren"
• Vermeiden: "Wie es funktioniert", "Hinter den Kulissen", "Wichtige Hinweise", es sei denn, der Abschnitt benötigt wirklich diese Form

Verwenden Sie präzise modale Sprache:

• Verwenden Sie "muss" für erforderliches Verhalten.
• Verwenden Sie "kann" für optionale Fähigkeit.
• Verwenden Sie "empfohlen" für den Standardpfad.
• Verwenden Sie "vermeiden" für bekannte Fallstricke.
• Erklären Sie "warum" nur dann, wenn es eine Entwicklerentscheidung beeinflusst.

Detaillierungsgrad

Variieren Sie den Detaillierungsgrad nach Seitentyp:

• Überblicksseiten: Seien Sie kurz; helfen Sie Lesern bei der Auswahl.
• Schnellstarts: Seien Sie prozessorientiert; enthalten Sie nur das, was für den ersten Erfolg nötig ist.
• Anleitungen: Seien Sie für einen Workflow vollständig; enthalten Sie Entscheidungen, Seiteneffekte und Fehlerbehandlung.
• Referenzen: Seien Sie erschöpfend; dokumentieren Sie jedes Feld, jeden Standardwert, Enum, nullbaren Wert, jede Einschränkung, Antwort und jeden Fehler.
• Fehlerbehebung: Seien Sie explizit; gehen Sie davon aus, dass der Leser blockiert ist und beobachtbare Prüfungen benötigt.

Gehen Sie in die Tiefe, wo Fehler teuer sind:

• Authentifizierung und Geheimnisverwaltung
• Geldbewegungen, Abrechnung, Berechtigungen und irreversible Aktionen
• Webhooks, Wiederholungen, doppelte Ereignisse und Reihenfolge
• Idempotenz und Nebenläufigkeit
• Unterschiede zwischen Sandbox und Produktion
• Versionierung, Migrationen und Rückwärtskompatibilität
• Limits, Ratenbegrenzungen, Kontingente und Zeitüberschreitungen
• Fehlercodes und Wiederherstellungspfade
• Datenaufbewahrung, Datenschutz und compliance-relevantes Verhalten

Vergraben Sie diese Details nicht in einer fernen Referenz, wenn Entwickler sie benötigen, um die Aufgabe sicher abzuschließen.

Beispiele

Gestalten Sie Beispiele produktionsnah, selbst wenn Sie Testdaten verwenden:

• Bevorzugen Sie vollständige, kopierbare Befehle oder Ausschnitte.
• Verwenden Sie realistische Variablen- und Wertnamen.
• Kennzeichnen Sie Platzhalter klar mit spitzen Klammern wie <API_KEY> oder <CUSTOMER_ID>.
• Zeigen Sie nach Befehlen die erwartete Erfolgsausgabe.
• Zeigen Sie für API-Referenzen vollständige Anforderungs- und Antwortbeispiele, wenn die Antwortform wichtig ist.
• Halten Sie eine konzeptionelle Einheit pro Codeblock.
• Verwenden Sie sprachspezifische Code-Umrandungen.
• Vermeiden Sie Spielzeugbeispiele, die erforderliche Einrichtung, Authentifizierung, Fehlerbehandlung oder Bereinigung verbergen.

Wenn mehrere Sprachen nützlich sind, behalten Sie dasselbe Szenario über Sprachen hinweg bei, damit Leser Entsprechungen vergleichen können.

Auffindbarkeit und Navigation

Gestalten Sie jede Seite so, dass Leser sie finden, darauf verlinken und schnell entscheiden können, ob sie ihre Frage beantwortet:

• Verwenden Sie zielorientierte Titel und Überschriften, die wahrscheinlichen Suchbegriffen entsprechen.
• Beginnen Sie jede Seite mit einer prägnanten Antwort auf "Was kann ich hier tun?"
• Fügen Sie Metadaten oder Frontmatter ein, die vom OpenClaw-Dokumentationsindex benötigt werden.
• Fügen Sie "Lesen Sie, wenn..."-Hinweise für die Dokumentenlisten-Routing hinzu, wenn Sie OpenClaw-Dokumentationsseiten erstellen oder ändern, die am Dokumentationsindex teilnehmen.
• Verlinken Sie von wahrscheinlichen Einstiegspunkten aus, nicht nur von benachbarten internen Taxonomieseiten.
• Halten Sie Abschnittsüberschriften stabil genug für Links aus Issues, PRs, Support-Antworten und Chat-Antworten.
• Ordnen Sie Tutorials und Beispiele von Voraussetzungen zu fortgeschrittenen Aufgaben; ordnen Sie Referenzseiten alphabetisch oder thematisch, wenn dies die Suche unterstützt.
• Geben Sie den Umfang vorab an, wenn eine Seite absichtlich unvollständig ist.

API-Referenzmuster

Für Endpunkte, Methoden, Objekte oder Befehle fügen Sie Folgendes ein:

1. Kurze Zweckbeschreibung.
2. Authentifizierungs- oder Berechtigungsanforderungen.
3. Anforderungsform, einschließlich Pfad, Abfrage, Header und Body-Felder.
4. Parametertabelle mit Typ, Pflichtfeld, Standardwert, Einschränkungen, Enum-Werten und Seiteneffekten.
5. Rückgabeform mit Objektlebenszyklus-Zuständen.
6. Fehlerfälle mit Codes, Ursachen und Wiederherstellungsleitfaden.
7. Ausführbares Beispiel einer Anforderung.
8. Repräsentative erfolgreiche Antwort.
9. Verwandte Anleitungen und angrenzende Referenzseiten.

Für verschachtelte Objekte dokumentieren Sie untergeordnete Felder in der Nähe ihres übergeordneten Elements. Zwingen Sie Leser nicht, zum Verständnis der Form einer einzelnen Anforderung über Seiten zu springen.

Verifikation

Überprüfen Sie Dokumentationsänderungen wie Produktänderungen:

• Führen Sie den relevanten Docs-Build, Docs-Index, Formatierer, Link-Checker oder generierten Dokumentationscheck aus, wenn verfügbar.
• Führen Sie Befehle, Ausschnitte und Beispiele aus, deren Ausführung die Seite dem Benutzer empfiehlt, wann immer machbar.
• Bestätigen Sie, dass Screenshots, UI-Beschriftungen, CLI-Ausgabe, Konfigurationsschlüssel, Flags, Standardwerte, Fehler und Dateipfade mit dem aktuellen Verhalten übereinstimmen.
• Bevorzugen Sie ausführbare Prüfungen gegenüber reiner Textüberprüfung für API-, CLI-, Konfigurations-, generierte Referenz- und Fehlerbehebungsdokumentation.
• Wenn ein Verifikationsschritt nicht machbar ist, geben Sie an, was nicht verifiziert wurde und warum.

Vollständigkeitsprüfungen

Bevor Sie eine Seite finalisieren, überprüfen Sie:

• Der erste Bildschirm sagt den Lesern, was sie erreichen können.
• Der empfohlene Pfad ist offensichtlich.
• Voraussetzungen sind explizit und testbar.
• Beispiele können mit dokumentierten Eingaben ausgeführt werden.
• Die Seite hat eine klare Zielgruppe: Benutzer, Betreiber, Plugin-Autor, Mitwirkender oder Betreuer.
• Testmodus- und Produktionsmodus-Verhalten sind getrennt.
• Sicherheitskritische Werte werden niemals in Beispielen offengelegt.
• Jede Warnung ist dem Schritt zugeordnet, wo sie relevant ist.
• Randfälle sind dort dokumentiert, wo sie die Implementierung betreffen.
• API-Felder enthalten Typen, Standardwerte, Einschränkungen und Fehler.
• Die Fehlerbehebung beginnt mit beobachtbaren Symptomen.
• Verwandte Links helfen dem Leser, fortzufahren, ohne die Seite zu duplizieren.
• Auf der Seite wird angegeben, wo Support erhalten, Issues gemeldet oder Beiträge geleistet werden können, wenn dies für den nächsten Schritt des Lesers relevant ist.
• Die Seite ist für den von ihr beanspruchten Umfang vollständig, oder die Einschränkung wird vorab genannt.

Review-Durchgang

Bearbeiten Sie in dieser Reihenfolge:

1. Entfernen Sie Wiederholungen und allgemeine Erklärungen.
2. Verschieben Sie konzeptionellen Hintergrund unter die erste nützliche Aktion, es sei denn, er ist für die richtige Auswahl erforderlich.
3. Ersetzen Sie passive oder abstrakte Formulierungen durch konkrete Anweisungen.
4. Straffen Sie Überschriften, bis die Gliederung wie eine Aufgabenkarte liest.
5. Fügen Sie fehlende betriebliche Details für die Produktionssicherheit hinzu.
6. Überprüfen Sie Beispiele auf Kopiergenauigkeit.
7. Fügen Sie Links zwischen Anleitungen, Referenzen, SDKs, Tests und Fehlerbehebungsflächen hinzu.
8. Überprüfen Sie Auffindbarkeit, Adressierbarkeit, Zugänglichkeit und Docs-as-Code-Verifikation.