Kolumne

Knigge für Softwarearchitekten: Die Lektorin

Peter Hruschka und Gernot Starke

Nachdem wir Ihnen im letzten Teil die starke Fokussierung auf Ergebnisse (statt Prozesse!) nahe gelegt haben, möchten wir diesmal auf Details eben dieser Ergebnisse eingehen: Da Schriftsprache ja immer noch das bevorzugte Mittel langfristiger menschlicher Kommunikation und Dokumentation bildet, sollten Sie als Architekt einige Grundregeln dazu beherzigen.

Der Knigge als Buch

Die beliebte Java-Magazin-Kolumne „Knigge für Softwarearchitekten“ gibt es jetzt auch als praktisches Kompaktbuch bei entwickler.press!

Die Buchversion wurde um zahlreiche Kapitel ergänzt. Zudem wurden die einzelnen Teile deutlich erweitert und enthalten zusätzliche Praxisberichte, Tipps und Ratschläge!

Der ideale Benimm-Ratgeber für Softwarearchitekten und solche, die es werden wollen!

Jetzt bestellen!

Die Lektorin

Nehmen Sie Sprache ernst. Legen Sie großen Wert auf verständliche, klare und einfache Sprache. Sie schreiben für Ihre Leser und Leserinnen, nicht zum Selbstzweck. Das alles halten Sie für selbstverständlich? Wir auch. Warum wirkt dann ein signifikanter Teil der uns bekannten technischen Dokumentation wie eine Mischung aus Schlaftablette und Streckbank (sprich: macht müde und tut weh)? Weil die Grundregeln guter Sprache eben doch nicht selbstverständlich sind. Wir haben für Sie kräftig in den großartigen Büchern von Peter Rechenberg [1] und Wolf Schneider [2] gelesen und einige Ratschläge daraus zusammengestellt.

Schaffen Sie Klarheit – in Kürze

Kurze Texte machen Ihren Lesern weniger Arbeit – Grund genug, auf Füllstoff möglichst zu verzichten. Wenn Sie Ihre Gedanken möglichst klar ausdrücken möchten, hilft eine kurze Erklärung, statt einer langen. Verzichten Sie in technischer Dokumentation auf Spannungsbögen und blumige Umschreibung. Klarheit bedeutet auch, treffende Worte zu finden. In der Programmierung kennen wir alle die Notwendigkeit „sprechender Bezeichner“ – gleiches gilt für Ihre schriftliche Kommunikation. Besonders warnen wir Sie vor missverständlichen oder mehrfach belegten Wörtern – etwa Komponente, System, Anwendung oder Funktionalität. Solche Begriffe haben in verschiedenen Kontexten unterschiedliche Bedeutung. Suchen Sie nach exakten, genau zutreffenden Wörtern. Verzichten Sie auf Überraschungen: Gleiche Dinge oder Konzepte sollten Sie grundsätzlich gleich benennen und auf Synonyme verzichten. Nehmen Sie Wiederholungen in Kauf, statt einmal von „Teilsystem“ und im nächsten Satz von „Modul“ zu schreiben – obwohl Sie genau das Gleiche damit meinen. Definieren Sie wichtige Begriffe, führen Sie ein Glossar und stimmen Sie dessen Inhalte genau ab. Wir meinen hier „genau“ im Sinne von „ganz genau“, nicht „ungefähr“.

Schreiben Sie einfach

Mit Kürze und Klarheit ist Einfachheit eng verbunden, erläutert [1]: „Einen Sachverhalt klar und kurz beschreiben heißt auch, ihn so einfach wie möglich beschreiben, mit einfachen Worten und einfach gebauten, unverschachtelten Sätzen.“

In Gesetzestexten oder amtlichen Verordnungen können Sie selbst leidvoll erfahren, wie außerordentlich lang und kompliziert Sätze der deutschen Sprache sein können. Ein Satz soll einen Gedanken ausdrücken, den Sie sich am besten VOR dem Schreiben schon gemacht haben. Übermäßig lange Sätze mit geschachtelten Nebensätzen wirken oft kompliziert und deuten auf schlechte Verständlichkeit hin.

Sie fragen jetzt, wie einfach es denn sein soll? Vordergründig ist dies natürlich durch den Sachverhalt selbst begründet: Manche komplexen oder komplizierten Aspekte in Ihren Systemen sollen Sie einfach darstellen, aber nicht vereinfachend.

Positiv formulieren

Wir möchten zur allgemeinen Erheiterung aus dem Bürgerlichen Gesetzbuch (BGB) der Bundesrepublik Deutschland zitieren – ein anschauliches Plädoyer für positive Formulierung [3]:

Paragraph 181 – Mangel der Ernstlichkeit: Eine nicht ernstlich gemeinte Willenserklärung, die in der Erwartung abgegeben wird, der Mangel der Ernstlichkeit werde nicht verkannt werden, ist nichtig.

Solche Formulierungen sind grausam: Das menschliche Gehirn benötigt für das Verständnis negativer Aussagen etwa 50% länger als für positive: Positive Formulierungen sind verständlicher. Das erläutert Wolf Schneider in [2] gemäß einer Veröffentlichung der Psychology Today. Wir vermuten, dass pro Negation ein beträchtlicher Faktor hinzukommt – je nein desto schlecht!

Negative können Leser leicht in die Irre führen. Ein Beispiel: „XML sollten Sie mit der ABC-Schnittstelle nicht verwenden.“ Was soll ich denn jetzt tun? Ist die ABC-Schnittstelle insgesamt gefährlich? Im schlimmsten Fall hört Ihr Leser vor dem Ende auf zu lesen.

Geschrieben von
Peter Hruschka und Gernot Starke
Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.