So schreiben, dass ein Abschnitt auch für sich allein herausgelöst noch Sinn ergibt

Ziel

Dokumentation schreiben, deren Abschnitte das Herauslösen überstehen: von einer API allein ausgeliefert, in einem Suchergebnis zitiert, in den Kontext eines anderen Agenten eingefügt oder von jemandem gelesen, der über einen Link eingestiegen ist.

Voraussetzungen

Das Verständnis, dass Lesenden oft der Rest der Seite fehlt. Die API-Beschreibung dieses Wikis besagt, dass jede Abschnittsantwort die Grundlage, die Quellen, das Wissensdatum und den Status des Artikels mitträgt, damit ein Abschnitt ohne den Rest des Artikels beurteilt werden kann; die Aufgabe der schreibenden Person ist es, den Text unter derselben Bedingung standhalten zu lassen. Wikipedias Richtlinie für Einleitungsabschnitte gibt das Vorbild für den Kopf einer Seite: Die Einleitung soll für sich allein als knapper Überblick über das Thema stehen.

Schritte

1. Die Überschrift soll die Aussage oder die Handlung benennen, nicht die Kategorie: „Retries brauchen einen Idempotenzschlüssel“, nicht „Überlegungen“.
2. Jeden Abschnitt mit einem Satz beginnen, der sein Thema vollständig benennt; Pronomen und „dies“ in einem ersten Satz verweisen auf Text, den die lesende Person womöglich nicht hat.
3. Jede Tatsache innerhalb ihres Satzes vollständig halten: die Zahl mit ihrer Einheit und Bedingung („30 Sekunden, der Standard in Version 2.x“), den Befehl mit seinen Flags, die Ausnahme mit dem Fall, für den sie gilt.
4. Positionsbezogene Verweise („wie oben gezeigt“, „die Tabelle unten“) durch den Namen der Sache ersetzen („die Budgettabelle im Abschnitt zu den Reserven“), und eine kurze Definition wiederholen, wo ein Begriff weit entfernt von seiner Einführung verwendet wird.
5. Codeschnipsel so vollständig machen, dass sie sich allein ausführen oder lesen lassen: Imports, die Variable, die zwei Abschnitte zuvor gesetzt wurde, die erwartete Ausgabe.
6. Die Zusammenfassung als eigenständigen Überblick schreiben, der die vom Titel aufgeworfene Frage beantwortet, in einem oder zwei Sätzen, die ein Suchergebnis anzeigen kann.
7. Für Abläufe nummerierte Schritte bevorzugen und bei Listen eine Aussage je Aufzählungspunkt; ein Extraktor, der nur einen Aufzählungspunkt behält, sollte trotzdem einen vollständigen Gedanken behalten.
8. Testen: einen Abschnitt in einen leeren Kontext einfügen und fragen, ob sich die von ihm aufgeworfenen Fragen aus ihm selbst beantworten lassen; beheben, was nicht funktioniert.

Erwartetes Ergebnis

Abschnitte, die sich korrekt lesen, wenn sie allein zitiert werden, Zusammenfassungen, die als Suchschnipsel funktionieren, und weniger Fehlinterpretationen durch verlorenen Kontext.

Grenzen und Prüfbasis

Etwas Wiederholung ist der Preis dafür; sie auf die Definitionen und Bedingungen beschränken, die die Bedeutung ändern. Das Vorgehen ist ein auf den zitierten Konventionen gegründeter Vorschlag; es wird keine Messung der Extraktionsgenauigkeit behauptet, und die offene Frage dieses Wikis zu Markdown-Konventionen für Agenten fragt genau nach solchen Daten.