Technische Dokumentation in reStructuredText mit echten Beispielen schreiben und den Build prüfen

## Erklären, was Leser brauchen, und tiefe Details dem Code überlassen Schreibe für Menschen, die das dokumentierte Verhalten verstehen und anwenden müssen. Erkläre Begriffe so klar und knapp wie möglich. Nimm technische Einzelheiten auf niedriger Ebene auf, wenn sie eine Entscheidung unterstützen, überlasse jedoch sehr tiefe Implementierungsdetails dem Quellcode. - Beschreibe eine Methodensignatur nur, wenn sie für die richtige Verwendung der Methode entscheidend ist. - Dokumentiere die Befehlsargumente und Optionen, die den Hauptarbeitsablauf beeinflussen, nicht jeden verfügbaren Schalter. - Wiederhole keine Fehler- oder Ausnahmebeschreibung, wenn die Meldung im Code Ursache und Abhilfe bereits verständlich erklärt. - Bevorzuge eine gezielte Erklärung, ein realistisches Beispiel und einen Verweis auf weiterführende Einzelheiten gegenüber einem vollständigen Katalog. ## Den Zweig nach Art der Änderung und den Release-Daten wählen Schreibe die Liste der gepflegten Versionen niemals fest in den Code. Lies vor der Wahl des Zielzweigs die maßgeblichen Veröffentlichungsmetadaten des Projekts und wende anschließend die Regeln für die jeweilige Änderungsart einheitlich an. - Fehlerbehebungen gehören in den ältesten gepflegten Zweig, der den Fehler enthält. - Dokumentation für eine neue Funktion gehört in den Zweig, in dem die Funktion eingeführt wurde. Wird dieser Zweig nicht mehr gepflegt, verwende den nächstfolgenden noch gepflegten Zweig. - Tippfehler, Umformulierungen, Umstrukturierungen und andere nicht funktionale Änderungen gehören in den ältesten gepflegten Zweig. - Dokumentation für unabhängig versionierte Teilprojekte folgt deren eigener erklärter Richtlinie. Wenn diese es verlangt, gehören alle Änderungen einschließlich neuer Funktionen in den ältesten gepflegten Zweig. Halte die Änderungsart und die für die Entscheidung verwendeten Wartungsdaten fest. Sind die Veröffentlichungsmetadaten nicht verfügbar oder mehrdeutig, darfst du den Zweig nicht erraten. ## Überschriftenzeichen und Zeilenlänge einheitlich halten Verwende die Unterstreichungszeichen für Überschriftsebenen durchgehend einheitlich: Gleichheitszeichen für Ebene 1, Bindestriche für Ebene 2, Tilden für Ebene 3, Punkte für Ebene 4 und doppelte Anführungszeichen für Ebene 5. Jede Unterstreichung muss die gesamte Länge des Überschriftentextes abdecken. Wende alle vom Repository festgelegten pfadspezifischen Ausnahmen an. Brich Fließtext bei 80 Zeichen um. Tabellen, URLs und einzelne Zeilen sind ausgenommen, wenn ein Umbruch die Lesbarkeit verschlechtern würde. Listenzeichen stehen am Zeilenanfang. Teile fett oder kursiv ausgezeichnete Bereiche nicht über mehrere Zeilen. Verwende für Quelltext im Fließtext paarweise doppelte rückwärts gerichtete Hochkommas. Nutze für Codebeispiele in der Standardsprache die knappe Form mit doppeltem Doppelpunkt, außer der Marker stünde allein in einer Zeile. Verwende eine ausdrückliche code-block-Direktive, wenn Sprache oder Darstellungskontext benannt werden müssen. ## Einrückung von Direktiven und Schreibweise von Links vereinheitlichen Rücke Direktiveninhalte um vier Leerzeichen ein. Lasse nach einem Marker mit doppeltem Doppelpunkt und vor seinem Inhalt eine Leerzeile. Lasse außerdem vor und nach jeder Direktive eine Leerzeile. Richte Fortsetzungszeilen eines mehrzeiligen Listeneintrags am Anfang seines Textes aus. Verwende den zur Aussage passenden Standardhinweis: note, tip, warning, caution oder seealso. Nutze für neu hinzugefügte und veraltete Funktionen die dafür vorgesehenen Direktiven mit der betreffenden Version und einer kurzen Erklärung. Verwende für interne Dokumentverweise absolute Dokumentpfade. Nutze für einen bestimmten Abschnitt einen beschrifteten Querverweis. Verwende niemals einen relativen internen Pfad. Lege benannte Verweisziele für externe Seiten am Dateiende ab, statt URLs direkt in den Fließtext einzubetten. Verwende die besonderen Rollen des Dokumentationssystems für Klassen, Methoden, Funktionen und eingebaute Typen der Sprach-API. ## Konfigurationsbeispiele wie YAML und XML immer gleich anordnen Unterstützt eine Funktion mehrere Konfigurationsformate, zeige alle unterstützten Formate in einer configuration-block-Direktive. Halte im gesamten Repository dieselbe Reihenfolge ein, damit Leser Seiten vergleichen können, ohne die Anordnung neu lernen zu müssen. - Für Dienste und allgemeine Konfiguration gilt die Reihenfolge YAML, XML, Programmiersprachenformat. - Für Weiterleitung, Validierung und Objektabbildung gilt die Reihenfolge Attribute, YAML, XML, Programmiersprachenformat. - Für Übersetzungsressourcen gilt die Reihenfolge XML, YAML, Programmiersprachenformat. Verwende gewöhnliche Registerkarten nur für parallele Inhalte, die keine Konfiguration darstellen, etwa alternative Werkzeuge oder Arbeitsabläufe. Unterscheiden sich Beispiele zwischen in ein Framework eingebundenen und eigenständigen Anwendungen, verwende unterschiedliche Sprachkennungen, damit Darstellungssystem und Leser die Zusammenhänge unterscheiden können. ## Codebeispiele mit echten Namen und einem Dateinamen-Kommentar schreiben Befolge die Programmierregeln der Zielsprache und die bewährten Vorgehensweisen des Projekts. Verwende realistische Namen und Situationen statt bedeutungsloser Platzhalterwörter. Nutze reservierte Beispieldomänen und den im Repository üblichen Musteranbieternamen. - Brich Zeilen in Codeblöcken nach Möglichkeit bei 85 Zeichen um. - Rücke Beispiele einschließlich YAML um vier Leerzeichen ein. - Nimm Namensraum- und Import-Anweisungen auf, wenn sie die Ausführung des Beispiels oder das Verständnis von Typen unterstützen. - Beginne einen Codeblock mit einem Kommentar, der den Dateinamen nennt. Füge danach nur dann eine Leerzeile ein, wenn die nächste Zeile ebenfalls ein Kommentar ist. - Setze vor jeden Shellbefehl eine Eingabeaufforderungsmarkierung. - Verwende beim Zusammenfassen ausgelassener Blöcke die zur Sprache passende Kommentarform. - Nutze beim Kürzen eines Wertteils in derselben Zeile nur Auslassungspunkte ohne Kommentarzeichen. - Bewahre formatspezifische Abstandsregeln, einschließlich erforderlicher Leerzeichen in eingebetteten YAML-Zuordnungen. Ein Beispiel soll den unterstützten Weg vermitteln, ohne eine vollständige Produktionsimplementierung vorzutäuschen. Lasse keine Voraussetzung aus, deren Fehlen den gezeigten Code scheitern ließe. ## Einfaches amerikanisches Englisch schreiben und Wörter wie „simply“ meiden Schreibe in amerikanischem Englisch. Verwende für Abschnittsüberschriften die englische Titelschreibweise: Schreibe das erste und letzte Wort sowie Hauptwörter groß und kurze Funktionswörter klein, außer sie stehen am Anfang des Titels. Sprich den Leser mit „you“ an, statt als „we“ zu sprechen. Verwende geschlechtsneutrale Pronomen. Bevorzuge Aktiv, einfachen Wortschatz und direkte Sätze, die für ein internationales Publikum verständlich sind. Kurzformen sind erlaubt. Verwende kein Oxford-Komma. Vermeide Redewendungen und herablassende Wörter wie „obviously“, „simply“, „just“, „easy“, „clearly“, „trivial“ und „of course“. Solche Wörter können fehlende Erklärungen verdecken und Leser entmutigen. Jedes Bild benötigt einen knappen Alternativtext, der mit einem Großbuchstaben beginnt und mit einem Punkt endet. Beginne ihn nicht mit „A screenshot of“ oder „Diagram of“. Erkläre komplexe Schaubilder im umgebenden Text, statt alle Einzelheiten in den Alternativtext zu zwingen. ## Vor dem Abschluss die Doku bauen und Warnungen und kaputte Links prüfen Schreibe Verzeichnisse mit abschließendem Schrägstrich und Dateierweiterungen mit vorangestelltem Punkt. Verwende in Verzeichnisbäumen einen neutralen Beispielprojektstamm wie `your-project/`. Halte Dateinamen, Pfade, Befehle und Verweisziele in Text und Beispielen einheitlich. Bevor eine Dokumentationsänderung als abgeschlossen gilt: 1. Installiere die Abhängigkeiten zur Dokumentationserstellung im vorgesehenen Erstellungsarbeitsbereich. 2. Führe den im Repository dokumentierten Erstellungsbefehl aus. 3. Stelle das erzeugte Ergebnis vorübergehend bereit, wenn eine Sichtprüfung erforderlich ist. 4. Prüfe geänderte Seiten auf Warnungen, fehlerhafte Verweise, falsch formatierte Direktiven, Codedarstellung, Überschriftenhierarchie und Bildbeschreibungen. 5. Bestätige, dass der gewählte Zielzweig weiterhin zur Änderungsart und zu den aktuellen Wartungsmetadaten passt. Melde keinen Erfolg allein aufgrund einer Quelltextprüfung, wenn das Repository eine Dokumentationserstellung bereitstellt.