hackycy/dokumentationserstellung

Erstellung Technischer Dokumentation

Wandeln Sie technische Dokumentation in einen stabilen, wartbaren und leicht navigierbaren Wissenskörper um. Entscheiden Sie zuerst, wo Fakten hingehören und was der Leser braucht, organisieren Sie dann den Inhalt und verfeinern Sie schließlich den Ausdruck.

Grundprinzipien

• Identifizieren Sie vor dem Schreiben den Informationstyp; machen Sie den Entdeckungsprozess nicht direkt zur Artikelstruktur.
• Jede dauerhafte Tatsache hat genau einen kanonischen Eigentümer; Eigentümer können Quellcode, Konfiguration, Schema, Generator, Dokumentation oder Entscheidungsprotokoll sein.
• Wählen Sie den Dokumententyp basierend auf der Leserintention, nicht aufgrund des Dateinamens oder vorhandenen Materials.
• Erstellen Sie vor dem Schreiben einen Document Contract: Leser, Ziel, Thema, Umfang, Ausschlüsse, Autoritätsquellen und Detailobergrenze.
• Der Dokumententyp darf den Umfang nicht erweitern; übergeordnete Dokumente fassen direkte Unterelemente zusammen und verlinken auf den Detail-Eigentümer.
• Organisieren Sie Inhalte nach Vorbedingungen, Abhängigkeiten und überprüfbaren Ergebnissen, nicht nach der Reihenfolge von Recherche, Implementierung oder Commits.
• Platzieren Sie aktuellen Zustand, Designbegründungen und historische Erzählungen in getrennten Dokumentverantwortlichkeiten.
• Verlinken Sie beim Überschreiten von Grenzen auf autoritative Details; behalten Sie nur Inhalte, die zum aktuellen Umfang passen und ausreichend stabil sind.
• Lassen Sie zuerst den Hauptagenten den Autorenplan einfrieren, bevor Sie über Delegierung entscheiden; Unteragenten führen nur lokal begrenzte Schreibaufgaben aus.

Arbeitsvertrag

Führen Sie vor dem Schreiben, Umschreiben, Aufteilen, Zusammenführen oder der Strukturprüfung einen kurzen Document Contract durch. Dies kann intern erfolgen; machen Sie es nur dann zu einem sichtbaren Artefakt, wenn die Aufgabe eine Abstimmung erfordert.

Erfassen Sie die folgenden Felder:

• Leserintention: Der Leser möchte lernen, eine Aufgabe erledigen, nachschlagen, verstehen, nachvollziehen oder Regeln befolgen.
• Dokumententyp: Der primäre Dokumententyp, der zur Intention passt; ein Dokument behält nur eine Hauptintention.
• Thema: Das Thema oder die Systemebene, für die das Dokument direkt verantwortlich ist.
• Umfang: Enthaltene Objekte, Verhaltensweisen und Tiefe.
• Ausschlüsse: Inhalte, die ausdrücklich anderen Dokumenten oder Autoritätsquellen vorbehalten sind.
• Autoritäten: Quellcode, Konfiguration, generierte Dateien, Entscheidungsprotokolle oder vorhandene Dokumente, die die aktuellen Fakten stützen.
• Detailobergrenze: Die höchste Detailebene, die unter dem aktuellen Thema und den Leserzielen zulässig ist.

Wenn Eigentümer, Leserintention, Umfang oder Autoritätsquellen nicht bestimmt werden können, bewahren Sie die Unsicherheit und melden Sie die Lücken; erfinden Sie keine Produktentscheidungen oder aktuelles Verhalten aus Erfahrung.

Autoren-Workflow

1. Aufgabe und Dokumentposition lokalisieren

Identifizieren Sie, ob es sich um Neuerstellung, Aktualisierung, Aufteilung, Zusammenführung oder Strukturüberprüfung handelt. Lesen Sie anwendbare AGENTS.md, CLAUDE.md, CONTEXT.md, das Dokumentenverzeichnis und benachbarte Dokumente, um die bestehenden Konventionen zu Hierarchie, Benennung und Verlinkung im Repository zu bestätigen.

Wenn das Zieldokument nicht existiert, behandeln Sie die Aufgabe als Greenfield-Dokumentation: Erstellen Sie eine Kandidaten-Dokumentenlandkarte aus Code-Verzeichnissen, öffentlichen APIs, Konfigurations-Schemas, Tests, Beispielen, Befehlen und generierten Dateien. Entscheiden Sie zuerst, ob ein einzelnes Einstiegsdokument oder eine Gruppe von Dokumenten benötigt wird, die nach Eigentümer und Leserintention aufgeteilt sind – komprimieren Sie nicht das gesamte Code-Gerüst in ein einziges, umfassendes Dokument.

Abschlussbedingung: Bei vorhandenen Dokumenten sind der Zielpfad, das übergeordnete Dokument, direkte Unterdokumente und die anwendbaren lokalen Regeln bekannt; ohne vorhandene Dokumente sind die Hauptgrenzen des Code-Gerüsts, die Kandidaten-Dokumentenliste, der vorläufige Eigentümer und die Autoritätsquellen für jedes Dokument bekannt.

2. Informationen inventarisieren und klassifizieren

Listen Sie die Fakten, Erklärungen, Schritte, Beispiele, Einschränkungen und historischen Materialien auf, die erhalten werden sollen. Klassifizieren Sie nach Informationstyp und unterscheiden Sie zwischen aktuellem Zustand, dauerhaften Gründen, Abläufen, Nachschlagewerken, Regeln, Vorfällen und generierten Inhalten.

Wenn Sie eine detaillierte Klassifikationstabelle benötigen, lesen Sie references/information-and-ownership.md.

Abschlussbedingung: Jeder Kandidateninhalt hat einen Informationstyp; es wurden keine Materialien unterschiedlichen Typs zu einem undefinierten Absatz vermischt.

3. Fakten an kanonischen Eigentümer weiterleiten

Suchen Sie für jede dauerhafte Tatsache einen vorhandenen Eigentümer. Bevorzugen Sie Quellcode, Konfiguration, Schema, Generator und vorhandene Entscheidungsprotokolle als Autoritätsquellen; die Dokumentation besitzt nur die Erklärungen, Abläufe oder stabilen Verträge, die in ihren Verantwortungsbereich fallen.

Inhalte mit vorhandenem Eigentümer behalten nur die notwendige Zusammenfassung und einen Link zum Eigentümer. Wenn mehrere widersprüchliche Eigentümer gefunden werden, melden Sie zuerst den Konflikt und dokumentieren Sie das zu lösende Autoritätsproblem.

Abschlussbedingung: Jede nicht-triviale Tatsache hat genau einen Eigentümer; das aktuelle Dokument repliziert keine autoritativen Details von anderen Orten.

4. Dokumententyp basierend auf Leserintention auswählen

Wählen Sie aus Leserzielen einen Typ wie Tutorial, How-to, Referenz, Erklärung, ADR, Richtlinie oder Postmortem. Weisen Sie einem Dokument nicht mehrere Haupttypen zu, nur weil es verschiedene Inhalte enthält; teilen Sie das Dokument auf, wenn die gemischte Intention die Navigation oder Wartung beeinträchtigt.

Lesen Sie references/document-types-and-composition.md für Typauswahl und Strukturmuster.

Abschlussbedingung: Sie können in einem Satz sagen: "Wer liest dieses Dokument zu welchem Zweck?" und einen primären Dokumententyp angeben.

5. Umfang und Detailobergrenze festlegen

Geben Sie Thema, Zielgruppe, Ziel, Einschlüsse, Ausschlüsse, Autoritätsquellen und Detailobergrenze an. Beschränken Sie das Dokument auf sein Thema, seine Hierarchieebene und die Verantwortlichkeiten direkter Unterelemente; verschieben Sie Mechanismen, Tests, Checklisten und Implementierungsdetails auf niedrigeren Ebenen zum Eigentümer.

Der Dokumententyp darf den Umfang nicht erweitern. Übergeordnete Dokumente beschreiben Zusammensetzung, Verantwortlichkeiten und allgemeines Verhalten; Unterdokumente besitzen Typdefinitionen, Parameter, Testmechanismen oder spezifische Vorgänge.

Abschlussbedingung: Jeder Abschnitt kann die Frage beantworten: "Wie dient er dem aktuellen Leserziel und Umfang?"; Material außerhalb der Grenzen hat bereits einen Zielort oder Link.

6. Ausführbaren Autorenplan erstellen

Ordnen Sie zuerst die Konzepte, die der Leser als Vorbedingung kennen muss, dann die darauf aufbauenden Vorgänge, Erklärungen oder Nachschlageinhalte. Verwenden Sie die dem Dokumententyp entsprechende Struktur; machen Sie die Reihenfolge von Recherche, Implementierung, Diskussion oder Commits nicht zur didaktischen Reihenfolge.

Halten Sie für große Dokumente eine Kapitelbaum-, Fakten-Eigentümer-, Kapitelabhängigkeits-, Zieldatei-, Ausschluss- und Abnahmebedingungsliste für jedes Kapitel fest. Der Plan muss es einem anderen Agenten ermöglichen, eine lokale Aufgabe zu erledigen, ohne die gesamte Struktur neu zu entwerfen.

Abschlussbedingung: Der Leser muss nicht zu späteren Abschnitten springen, um notwendige Begriffe, Vorbedingungen oder Aktionen zu verstehen; jeder Hauptabschnitt dient einer klaren Frage; jede Planeinheit hat einen eindeutigen Umfang und eine Abschlussbedingung.

7. Ausführungsmodus auswählen und delegieren

Standardmäßig wird der Single-Agent-Pfad verwendet. Die Delegierung an Unteragenten erfolgt nur, wenn alle folgenden Bedingungen erfüllt sind:

• Der Plan wurde eingefroren; Leserintention, Dokumententyp, Umfang, Eigentümer und Hauptstruktur weisen keine ungelösten Konflikte auf.
• Es gibt mindestens zwei Arbeitseinheiten, die unabhängig gelesen, geschrieben und abgenommen werden können.
• Jede Arbeitseinheit hat einen eindeutigen Zieldatei- oder Kapitel-Eigentümer; Aufgaben bearbeiten nicht gleichzeitig denselben Textabschnitt.
• Abhängigkeiten wurden explizit dokumentiert; gemeinsam genutzte Fakten haben bereits eine Autoritätsquelle, anstatt dass Unteragenten gegenseitig raten.
• Die Kosten für Delegierung und Zusammenführung sind niedriger als die Kosten des Hauptagenten, der den gesamten Dokumentkontext durchgehend trägt.

Wenn die Bedingungen erfüllt sind, lesen Sie references/orchestration-and-delegation.md, lassen Sie den Hauptagenten ein Delegierungsbriefing erstellen und rufen Sie Unteragenten auf. Der Hauptagent behält den globalen Plan, die Faktenzuordnung, die Querverweise zwischen Kapiteln, die Zusammenführungsentscheidungen und die endgültige Abnahme. Unteragenten ändern nicht den Dokumententyp, modifizieren keine anderen Arbeitseinheiten und präsentieren keine unbewiesenen Fakten als Schlussfolgerungen.

Wenn die Bedingungen nicht erfüllt sind, führt der Hauptagent das Schreiben allein fort. Einzeldatei-Ergänzungen, kleinere Absatzrevisionen, Aktualisierungen einer Referenz mit einem einzigen Eigentümer und stark serielle Abhängigkeiten fallen alle in den Single-Agent-Pfad.

Abschlussbedingung: Es wurde klar zwischen Single-Agent- und delegierter Ausführung gewählt; bei Delegierung haben alle Aufgaben Grenzen, Abhängigkeiten, Ausgabeformate und Abnahmebedingungen.

8. Aktuellen Vertrag und beobachtbares Verhalten direkt schreiben

Drücken Sie Inhalte mit konkreten Subjekten, Aktionen, APIs, Optionen und Ergebnissen aus. Schreiben Sie zuerst den aktuellen Zustand und das für den Leser beobachtbare Verhalten, dann ergänzen Sie Standardwerte, Einschränkungen, Ausnahmen, Gründe und Abwägungen. Unterscheiden Sie klar zwischen "muss", "standardmäßig", "empfohlen" und "kann".

Tutorials und How-tos können sich auf ein Minimalbeispiel als Erklärungszentrum stützen; Referenzen auf abrufbare Definitionen und Grenzen; ADRs und Postmortems behalten ihre erforderlichen Begründungen oder Zeitlinien.

Wenn Sie eine vollständige Ausdrucksregeln und Checklisten benötigen, lesen Sie references/writing-and-validation.md.

Abschlussbedingung: Der Haupttext stellt wartbare Fakten, Verträge oder Schritte dar, nicht Denkprozesse, Implementierungsprotokolle oder vage Meta-Diskurse; die Ausgaben delegierter Aufgaben wurden an den Hauptagenten zurückgegeben.

9. Zusammenführen und vereinheitlichen

Wenn Unteragenten verwendet wurden, prüft der Hauptagent jede Ausgabe einzeln gegen den Autorenplan. Lösen Sie doppelte Fakten, Terminologie-Abweichungen, Kapitelgrenzen, Querverweise und Stil-Inkonsistenzen auf; erfassen Sie ungelöste Probleme zentral, lassen Sie keine lokalen Agenten globale Entscheidungen erfinden. Übernehmen Sie keine Prozessbeschreibungen der Unteragenten direkt in den Haupttext, sondern nur wartbare Ergebnisse.

Abschlussbedingung: Jede delegierte Einheit hat ein Ergebnis oder einen klaren Blockierungsgrund; dieselbe Tatsache hat nicht mehrere Eigentümer; das globale Inhaltsverzeichnis, Links, Terminologie und Leserpfade sind konsistent.

10. Verlinken, kürzen und validieren

Entfernen Sie doppelte Fakten, manuell abgeschriebene Listen, irrelevanten Hintergrund und Details, die die Detailobergrenze überschreiten. Verlinken Sie mit zielgerichteten Links zu Eigentümern, Unterdokumenten, Quellcode und Entscheidungsprotokollen. Führen Sie strukturelle und sprachliche Validierungen gemäß der Reihenfolge in den Referenzdateien durch.

Abschlussbedingung: Eigentümer, Typ, Umfang, Abhängigkeitsreihenfolge, aktuelle/historische Grenzen, Links und Ausdrucksregeln wurden überprüft; es wurden keine ungelösten Konflikte oder Ungewissheiten zurückgelassen.

Grenzen

Schreiben Sie keine repositoriespezifischen Dateihierarchien, Skriptbefehle, Wortbudgets, Codeblock-Kompilierungsregeln, zweisprachigen Abläufe oder spezifische Terminologie als allgemeingültige Regeln. Lesen Sie die lokalen Projektkonventionen und befolgen Sie diese; dieser Skill bietet nur ein projektübergreifend stabiles Dokumentationsentscheidungsrahmenwerk.

Behandeln Sie README, architecture.md oder AGENTS.md nicht als feste, universelle Dokumententypen. Bestimmen Sie zuerst die Leserintention und folgen Sie dann den spezifischen Konventionen des Projekts für diese Medien.

Übergabe

Geben Sie nach Abschluss kurz an: Dokumententyp und Leserintention, Behandlung kanonischer Eigentümer, Umfangsgrenzen, beteiligte Links oder Aufteilungen sowie noch menschlich zu entscheidende Tatsachenkonflikte. Tarnen Sie ungelöste Probleme nicht als aktuellen Zustand.