Gewinne:
- Möglichkeit, README-, Docstring- und Changelog-Entwürfe basierend auf Zielgruppe und Quelle mit KI zu erstellen
- Möglichkeit, die Ebenen „Was/Wie“ und „Warum“ in der Dokumentation zu trennen und das „Warum“ als Mensch hinzuzufügen
- Überprüfen Sie die Installationsschritte, indem Sie sie persönlich ausführen und das Dokument zu einem Teil der Codeänderung machen
Der am häufigsten vernachlässigte, aber langlebigste Teil der Software ist die Dokumentation. Der Code ist auch nach Monaten noch lesbar; Die Person, die es geschrieben hat, ist verschwunden, der Kontext ist vergessen und nur das, was geschrieben wurde, bleibt übrig. Eine gute README-Datei (Einführungsdokument, das erklärt, was ein Projekt ist und wie man es installiert und ausführt), erklärende Codekommentare und eine aktuelle API-Dokumentation (eine Referenz, die erklärt, wie man eine Schnittstelle verwendet) bestimmen direkt die Geschwindigkeit eines Teams. KI nimmt der Dokumentation einen Großteil der „Schreibmüdigkeit“ ab – bringt aber auch eine Falle mit sich: KI kann aus dem Code ableiten, was er tut, weiß aber oft nicht, warum es so gemacht wird.
In dieser Einheit erfahren Sie, wie Sie mit KI eine README-Datei, einen Codekommentar, einen Dokumentstring (pro Funktion/Klasse geschriebener Kommentarblock), ein API-Dokument und ein Änderungsprotokoll erstellen. und wie man den wertvollsten Teil der Dokumentation menschlich bewahrt: das „Warum“.
Unterscheidung zwischen „Was“ und „Warum“
Es gibt zwei Dokumentationsebenen. Das erste ist was/wie: „Diese Funktion sortiert eine Liste“, „Führen Sie diesen Befehl zur Installation aus“. Diese können aus dem Code und der Struktur extrahiert werden; KI zeichnet sich hier aus. Zweitens, warum: „Warum haben wir diesen Dienst asynchron statt synchron gemacht“, „warum beträgt dieser Grenzwert 30 Sekunden“, „warum haben wir diese Bibliothek der anderen vorgezogen“. Diese sind nicht im Code geschrieben; Es ist das Produkt von Designentscheidungen, Einschränkungen und vergangenen Schmerzen.
KI weiß nicht, „warum“; Bestenfalls handelt es sich dabei um eine vernünftige Vermutung – was gefährlich ist, denn ein falscher Grund ist schlimmer als gar kein Grund. Die Arbeitsteilung ist also klar: KI entwirft das „Was/Wie“, Sie fügen das „Warum“ hinzu. Der wertvollste Kommentar ist der, der sagt, was der Code nicht sagen kann.
Tipp: Wiederholen Sie nicht mit einem Kommentar, was der Code selbst klar sagt (wie i = i + 1 // i um eins erhöhen). KI produziert manchmal solche überflüssigen Kommentare; Beseitigen Sie sie und widmen Sie Ihre Energie den „Warum“-Kommentaren.
Schritt für Schritt: Dokumentationserstellung mit KI
- Geben Sie die Zielgruppe an. „Ein Entwickler, der gerade erst am Anfang steht“, „das externe Team, das diese API verwenden wird“, „das zukünftige Ich“ – das Publikum gibt den Ton für Sprache und Tiefe an.
- Geben Sie die Quelle an. Fügen Sie der Eingabeaufforderung den relevanten Code, die vorhandene README-Datei und ein Beispiel für die Verwendung hinzu. Ein Dokument ohne Quellenangabe ist eine Einladung zur Fälschung.
- Ausschießstruktur. Standardabschnitte für README (Zweck, Installation, Verwendung, Konfiguration, Beitrag), Projektformat für Dokumentzeichenfolge.
- Markieren Sie die „Warum“-Leerzeichen. Bitten Sie die KI, Entscheidungen, deren Begründung sie nicht kennt, als „hier ist eine ‚Warum‘-Notiz erforderlich“ zu kennzeichnen; Dann füllen Sie diese Lücken aus.
- Verifizieren. Führen Sie die Installationsschritte tatsächlich aus. Probieren Sie den Beispielcode aus. Eine README-Datei, die nicht funktioniert, ist schlimmer als gar keine README-Datei.
Drei Mini-Hüllen
Fall 1 – README beschleunigtes Onboarding. Die README-Datei eines Open-Source-Tools fehlte. Neue Mitwirkende hatten durchschnittlich 2 Stunden mit der Installation zu kämpfen. Das Team übergab AI die Installationsskripte und package.json und entwarf eine strukturierte README-Datei, führte dann die Schritte selbst auf einer sauberen Maschine aus und fügte die beiden fehlenden Abhängigkeiten hinzu. Die Installationszeit für nachfolgende Mitwirkende verringerte sich auf durchschnittlich 25 Minuten.
Fall 2 – Die erfundene „Warum“-Falle. Ein Entwickler hat die KI um einen Kommentar neben einem Timeout-Wert (timeout=30) gebeten. Die KI schrieb eine vernünftige, aber falsche Begründung, „hohe Netzwerklatenz zu tolerieren“; Der wahre Grund war die vertragliche 30-Sekunden-Grenze eines Downstream-Dienstes. Die Fehlinterpretation führte dazu, dass ein nachfolgender Entwickler den Wert unnötig erhöhte, was zu einem Vorfall führte. Lektion: Der Codeeigentümer muss die Begründung überprüfen.
Fall 3 – Der Docstring-Standard wurde automatisiert. Ein Hilfsmodul mit 40 Funktionen hatte keine Dokumentzeichenfolgen. Der KI wurde das Projektformat (Google-Stil) vorgegeben und für jede Funktion Parameter-, Rückgabe- und Ausnahmebeschreibungen erstellt; Der Entwickler hat diese überprüft und einige falsche Typdeklarationen behoben. Die Dokumentation von 40 Funktionen dauerte von etwa einem halben Tag auf eine Stunde.
Vier kopierbare Vorlagen
Strukturierter README-Entwurf:
Zielgruppe: {{z.B. neuer Mitwirkender}}.Schreiben Sie einen README-Entwurf basierend auf den folgenden Dateien. Abschnitte: Zweck, Funktionen, Anforderungen, Installation, Betrieb, Konfiguration, Tests, Beitrag. Extrahieren Sie Installations-/Ausführungsbefehle aus tatsächlichen Dateien. BESCHLAG. Markieren Sie die Orte, an denen Sie sich nicht sicher sind, mit „[VERIFY]“. Quelle: {{package.json / scripts / Beispielcode}}
Docstring/API-Referenz:
Schreiben Sie eine Dokumentzeichenfolge für diese Funktionen im Format {{Projektstil: Google/NumPy/JSDoc}}: kurze Zusammenfassung, Parameter (Typ + Bedeutung), Rückgabe, ausgelöste Ausnahmen, 1 kurzes Beispiel. Wiederholen Sie nicht, was der Code KLAR sagt. Markieren Sie Designentscheidungen, die ein „Warum“ erfordern, als „[WARUM ERFORDERLICH]“ und schreiben Sie keine erfundene Begründung.{{code}}
Leerzeichen für „Warum“-Kommentar entfernen:
In diesem Code könnte der nächste Entwickler fragen: „Warum ist das so?“ (magische Zahlen, ungewöhnliche Entscheidungen, Workarounds). Geben Sie jeweils einen Kommentar SKELETON ein, aber lassen Sie die Begründung LEER; Ich werde die Begründung ausfüllen.{{code}}
Changelog/PR-Erklärung:
Schreiben Sie einen {{Changelog-Eintrag / PR-Beschreibung}} aus dem Diff unten. Format: Was hat sich geändert (in der Benutzersprache), Warum (Problem: {{...}}), Wichtige Änderung (falls vorhanden), Wurde sie getestet? Passen Sie den Fachjargon an die Zielgruppe an.{{diff}}
Schwache Eingabeaufforderung / Starke Eingabeaufforderung
Schwach: „Schreiben Sie eine README-Datei für dieses Projekt.“
Strong: „Zielgruppe: ein Entwickler, der dieses Repo zum ersten Mal klont. Schreiben Sie auf der Grundlage der angehängten Dateien package.json, docker-compose.yml und scripts/ einen README-Entwurf mit den Abschnitten „Zweck“, „Anforderungen“, „Installation“, „Betrieb“, „Testen“ und „Beitrag“. Extrahieren Sie die Befehle aus diesen Dateien, erfinden Sie sie nicht; markieren Sie alle Stellen, an denen Sie sich nicht sicher sind, mit [VERIFY].“
Die starke Version gibt das Publikum, die Quelle, die Struktur und die „Make it, mark it“-Regel vor; so dass das Dokument auf echten Akten basiert und die zu überprüfenden Orte klar erkennbar sind.
Dokumenttyp
KI schneidet gut ab
Mensch fügt hinzu/überprüft
README-Installation
Schrittübersicht
Führen Sie die Schritte aus und bestätigen Sie
Dokumentzeichenfolge/API
Struktur, Parameter, Typ
Richtiger Typ und „Warum“
Codekommentar
Zusammenfassung „Was er tut“.
„Warum ist das“ Begründung
Changelog/PR
erster Entwurf
Wirkung und Genauigkeit
Architekturentscheidung (ADR)
Skelett
Echte Entscheidungen und Kompromisse
Dokumentation erfordert Wartung
Der gefährlichste Aspekt eines Dokuments besteht darin, dass es wahr erscheint, obwohl es falsch ist. Wenn sich der Code ändert und das Dokument nicht aktualisiert wird, führt es den Leser aktiv in die Irre. KI macht Aktualisierungen einfach: Geben Sie einen Unterschied aus und fragen Sie: „Welche Teile des Dokuments sind von dieser Änderung betroffen?“ Sie fragen sich vielleicht. Aber es ist der Prozess, der die Aktualität gewährleistet – machen Sie die Dokumentationsaktualisierung zu einem Teil der Codeänderung (PR-Akzeptanzkriterium). KI beschleunigt sich; Das Team baut Disziplin auf.
Achtung: Veröffentlichen Sie nicht, ohne die Installationsschritte in einer README-Datei zu überprüfen. Ein „wahrscheinlich funktionierendes“ Dokument kann den ersten Tag eines neuen Entwicklers ruinieren und das Vertrauen untergraben. Führen Sie die Schritte selbst in einer sauberen Umgebung durch.
Häufige Fehler
- Das „Warum“ passend zur KI ermitteln. Eine falsche Rechtfertigung ist schlimmer als keine Rechtfertigung; Der Codebesitzer sollte den Designgrund schreiben.
- Die Installationsschritte werden nicht überprüft. README, das nicht funktioniert, zerstört Vertrauen.
- Unnötiger Kommentar, der den Code wiederholt. Es erzeugt Lärm und verdeckt echte „Warum“-Interpretationen.
- Keine Angabe der Zielgruppe. Ein Dokument, bei dem unklar ist, an wen es geschrieben ist, nützt weder dem Anfänger noch dem Experten.
- Trennung des Updates vom Prozess. Wenn das Dokument nicht mit dem Code aktualisiert wird, wird es schnell irreführend.
Zusammenfassend
KI entlastet die Dokumentation erheblich von der mechanischen Belastung: schnelle Entwürfe, README, Dokumentzeichenfolge, API-Referenz, Änderungsprotokoll und PR-Beschreibungen. Aber es kann das „Warum“ nicht kennen, das die wertvollste Schicht ist, und es ist gefährlich, es zu erfinden. Die Arbeitsteilung ist klar: KI produziert das „Was/Wie“, Sie fügen das „Warum“ hinzu. Geben Sie die Zielgruppe an, stellen Sie Ressourcen bereit, legen Sie eine Struktur fest, markieren Sie die passenden Stellen und überprüfen Sie jeden Installationsschritt, indem Sie ihn selbst ausführen. Machen Sie die Dokumentation zu einem integralen Bestandteil der Codeänderung.
Anwendungsaufgabe
Wählen Sie ein Modul oder kleines Projekt, dessen Dokumentation fehlt oder veraltet ist. Generieren Sie zunächst eine Gliederung aus AI mit der Vorlage „Strukturierter README-Entwurf“ (oder Docstring); Geben Sie unbedingt die Quelle und die Zielgruppe an. Gehen Sie dann jeden Punkt durch, an dem die KI [VERIFY] oder [WARUM ERFORDERLICH] markiert hat: Führen Sie tatsächlich die Einrichtungsschritte aus und tragen Sie die „Warums“ des Designs mit Ihrem eigenen Wissen ein. Beachten Sie, wie viele Schritte behoben werden müssen und wie viele „Warum“ Sie hinzugefügt haben.
Checkliste
- [ ] In der Dokumentation unterscheide ich die Ebenen „Was/Wie“ und „Warum“.
- [ ] Ich lasse nicht die KI das „Warum“ erfinden, sondern füge es selbst hinzu.
- [ ] Ich gebe der Eingabeaufforderung die Zielgruppe und die tatsächlichen Quelldateien an.
- [ ] Ich überprüfe die von der KI markierten [VERIFY]-Punkte, indem ich sie persönlich ausführe.
- [ ] Ich eliminiere unnötige Kommentare, die den Code wiederholen.
- [ ] Ich mache die Dokumentationsaktualisierung zum Teil der Codeänderung.