Ein Änderungsprotokoll schreiben, das sagt, was sich geändert hat und was zu tun ist

## Klären, wer das Änderungsprotokoll liest und welche Änderungen diese Menschen betreffen Verfasse ein Änderungsprotokoll für Menschen, die von Änderungen an der Software betroffen sind, und nicht als maschinell validierte Spezifikation oder ungefilterte Auflistung der Entwicklungsaktivitäten. Jede redaktionelle Entscheidung sollte es den Lesenden erleichtern, die Veröffentlichung zu verstehen. Kläre vor dem Verfassen: - Die beschriebene Veröffentlichung oder Version. - Die Menschen, die auf das Produkt, die Bibliothek, den Dienst oder die Dokumentation angewiesen sind. - Die Änderungen, die Verhalten, Erwartungen, Kompatibilität, Barrierefreiheit, Sicherheit oder erforderliche Maßnahmen beeinflussen. - Die bereits im Projekt verwendeten Konventionen für Versionierung, Überschriften und Einträge. Nutze Konventionen als Werkzeuge und nicht als Ersatz für Urteilsvermögen. Behalte eine bestehende Struktur bei, wenn sie den Lesenden den Vergleich von Veröffentlichungen erleichtert, aber zwänge eine Änderung nicht in eine irreführende Formulierung, nur um eine Bezeichnung zu erfüllen. Wenn eine Regel strikt sein muss, erläutere den Grund, damit Mitwirkende sie sachgerecht anwenden können. Trenne die Grundsätze für Änderungsprotokolle von Einrichtungsanweisungen und üblichen Verfahren für Beiträge. Pflege für jede Art von Anleitung einen einzigen maßgeblichen Ort und verlinke darauf, statt Anweisungen zu duplizieren, die mit der Zeit voneinander abweichen können. ## Nur Änderungen aufnehmen, die Lesende betreffen, und sagen, warum sie wichtig sind Prüfe mögliche Änderungen aus Sicht der Lesenden. Nimm einen Punkt auf, wenn er verändert, was eine Person tun, beobachten, als verlässlich voraussetzen, konfigurieren, migrieren oder schützen kann. Schließe interne Aktivitäten ohne bedeutsame Auswirkungen aus, es sei denn, sie erklären eine relevante betriebliche Folge oder eine Auswirkung auf die Kompatibilität. Beantworte für jede aufgenommene Änderung: 1. Was hat sich in beobachtbaren Begriffen geändert? 2. Wer ist unter welchen Bedingungen betroffen? 3. Warum ist die Änderung wichtig? 4. Müssen die Lesenden handeln, und wenn ja, welche Maßnahme ist erforderlich? Beginne mit dem Ergebnis. Ergänze nur den Kontext, der erforderlich ist, um Missverständnisse zu vermeiden. Benenne Bedingungen, Ausnahmen und Folgen für die Migration ausdrücklich; verstecke sie nicht hinter einer vagen Zusammenfassung. Wirb nicht allein deshalb für ein bestimmtes Werkzeug, weil es beliebt ist, und erfinde keinen Ablauf, der kein nachgewiesenes Kommunikationsproblem löst. Bevorzuge einen einfachen Eintrag und den bestehenden Arbeitsablauf des Projekts, sofern der aktuelle Ansatz die Lesenden nicht daran hindert, eine wichtige Änderung zu verstehen. Richtlinien und Empfehlungen sollten ihre Begründung enthalten. Lesende sollten sachkundig widersprechen können, weil die Abwägung und der beabsichtigte Nutzen erkennbar sind. ## Jede Änderung in einfachen Worten beschreiben, mit Auswirkung und nötigen Schritten Verwende klare Sprache und nenne das Wesentliche zuerst. Vermeide ausgrenzende Zugangshürden, interne Kurzformen, schmückende Komplexität und Sätze, bei denen die Lesenden die Hauptaussage selbst rekonstruieren müssen. Bevorzuge Formulierungen, die Menschen mit einer anderen Muttersprache beim ersten Lesen verstehen und die sich direkt übersetzen lassen, statt von Übersetzenden neu gedeutet werden zu müssen. Halte diese Elemente klar voneinander getrennt: - Die Änderung selbst: eine konkrete Beschreibung des bisherigen und des neuen Verhaltens. - Die Auswirkung: die betroffenen Benutzerinnen und Benutzer, Umgebungen, Versionen oder Arbeitsabläufe. - Der Grund: das gelöste Problem oder der geschützte Grundsatz. - Die Maßnahme: jeder Schritt zur Aktualisierung, Konfiguration, Migration oder Überprüfung, den die Lesenden durchführen müssen. Stelle Gewissheit oder Auswirkungen nicht übertrieben dar. Wenn ein Verhalten vom Kontext abhängt, benenne die Bedingung, statt eine allgemeingültige Anweisung zu erteilen. Wenn keine Maßnahme seitens der Lesenden erforderlich ist, erfinde keine. Verwende die Terminologie über Einträge und Versionen hinweg einheitlich. Erläutere unvermeidbare Fachbegriffe bei ihrer ersten Verwendung, bewahre wichtige Unterscheidungen und vermeide beschönigende Formulierungen, die Warnungen oder Informationen zu inkompatiblen Änderungen abschwächen. Wende denselben klaren, auf das Wesentliche ausgerichteten Stil auf zugehörige Dokumentation, Hinweise für Mitwirkende und Commit-Nachrichten an, damit das Änderungsprotokoll durch konsistente Ausgangsinformationen gestützt wird. ## Prüfen, ob Übersetzungen dasselbe sagen wie das Original, und einen Menschen entscheiden lassen Behandle Übersetzungen als gleichrangige Kommunikation von Änderungen. Eine versionsspezifische Übersetzung muss entweder vorhanden sein oder klare Hinweise dazu geben, wie sie beigetragen werden kann. Sie muss genau und mit der maßgeblichen Quelle konsistent bleiben und zugleich in ihrer eigenen Sprache und ihrem kulturellen Kontext verständlich sein. Halte Seitenstruktur, Versionszuordnung und Quellauszeichnung so einfach, dass sie von Übersetzenden ohne Programmierkenntnisse bearbeitet werden können. Bevor du Überschriften, Bezeichner, Versionsbeziehungen oder Auszeichnungskonventionen änderst, prüfe, wie sich die Änderung auf jede gepflegte Sprache und Version auswirkt. Nutze diese Prüfreihenfolge: 1. Lege die Bedeutung des maßgeblichen Eintrags vor der Übersetzung endgültig fest. 2. Halte fest, welche Versionen und Sprachen die Änderung benötigen. 3. Prüfe, ob jede erforderliche Übersetzung vorhanden ist oder ob es einen klaren Weg gibt, sie beizutragen. 4. Vergleiche die übersetzte Bedeutung mit der maßgeblichen Quelle auf Auslassungen, Umkehrungen, veränderte Bedingungen und uneinheitliche Terminologie. 5. Lass eine Person, die Sprache und Kultur kennt, die endgültige redaktionelle Entscheidung treffen. Verwende keinen maschinell erzeugten Text als Ersatz für Übersetzende. Automatisierte oder modellgestützte Prüfungen können fehlende Abdeckung und mögliche Unstimmigkeiten aufspüren, aber für Bedeutung, kulturelle Angemessenheit und endgültige Formulierung tragen Menschen die Verantwortung. ## Wiederholte Prüfungen einfachen Werkzeugen überlassen, Entscheidungen den Menschen Nutze Automatisierung, um wiederholte Prüfungen über Sprachen, Versionen und Darstellungsumgebungen hinweg zu verringern. Geeignete Bereiche sind unter anderem Prüfungen der Übersetzungsabdeckung, Tests der Versionszuordnung, Hilfsmittel zum semantischen Vergleich, Prüfungen der Barrierefreiheit sowie visuelle oder funktionale Regressionstests. Bevorzuge gewöhnliche, wiederverwendbare Werkzeuge, die nach ihrer Erstellung lokal oder ohne Netzverbindung und ohne ein Modell ausgeführt werden können. Ein Sprachmodell kann einmalig beim Entwurf oder bei der Umsetzung eines Werkzeugs helfen, doch die daraus entstehende Prüfung sollte einsehbar, wiederholbar, kostengünstig ausführbar und eigenständig nutzbar sein. Modelle dürfen nicht: - Menschliche Übersetzende oder die kulturelle Prüfung ersetzen. - Die redaktionellen Positionen des Projekts oder die Bedeutung seiner Leitlinien bestimmen. - Eine Funktion oder einen Ablauf rechtfertigen, für die beziehungsweise den kein eigenständiger Bedarf besteht. Menschen entscheiden, ob ein Eintrag im Änderungsprotokoll korrekt, nützlich und angemessen ist. Werkzeuge liefern Belege; sie treffen nicht die Schlussfolgerung. Halte das Veröffentlichungssystem einfach und langlebig. Bevorzuge die vorhandene Werkzeugkette für Erstellung und Veröffentlichung und füge eine Abhängigkeit, einen Dienst, eine Datenbank oder eine neue Laufzeitumgebung nur hinzu, wenn eine konkrete Anforderung mit dem aktuellen Ansatz nicht sicher erfüllt werden kann. Prüfwerkzeuge, die ausschließlich für die Entwicklung bestimmt sind, dürfen nicht zu unnötigen Anforderungen an die Produktionsumgebung werden. Bestätige vor der Veröffentlichung, dass der maßgebliche Eintrag klar ist, die erforderlichen Versionen und Übersetzungen abgedeckt sind, automatisierte Prüfungen tatsächliche Ergebnisse erbracht haben und ein Mensch die endgültige Bedeutung geprüft hat.