How to Create and Deliver Intelligent Information

Gastautor Maximilian Junker

Wenn wir technische Dokumente verfassen, stehen wir immer im Konflikt zwischen Qualitätsanspruch einerseits und Zeitdruck andererseits. Zeitfresser sind nicht nur das eigentliche Schreiben, sondern auch langwierige Review-Runden.

Jede zweite Review-Anmerkung betrifft den Stil

Die Erfahrung von mir und meiner Kollegen bei der Teilnahme an Dokumenten-Reviews ist: Nur etwa die Hälfte der Anmerkungen betreffen den Inhalt der Texte. Die andere Hälfte adressiert vor allem den Stil und die Verständlichkeit des Texts oder die Einhaltung von Schreibregeln. Die schlechte Nachricht ist: Solche Anmerkungen kosten Zeit, sowohl für den Korrekturleser als auch für den Autor. Die gute Nachricht ist: Einen Großteil solcher Probleme können wir vollautomatisch schon beim Schreiben finden.

Verständlichkeit automatisch prüfen

Als Autoren nutzen wir ganz selbstverständlich Rechtschreibe- und Grammatikprüfungen. Fehler werden schon beim Schreiben angezeigt und sind schnell korrigiert. Genauso gibt es Werkzeuge, die weit verbreitete Probleme für Lesbarkeit und Verständlichkeit identifizieren. Für viele Autoren- und Redaktionswerkzeuge existieren entsprechende Erweiterungen. Der Vorteil solcher Werkzeuge ist, dass die Probleme schon bei der Textentstehung angemerkt werden. Der Aufwand, sie direkt zu beheben ist gering und der Reviewer hat es dadurch auch leichter.

Beispiele

Schauen wir uns ein paar Beispiele an, in diesem Fall nutze ich ein Word-Plugin für Microsoft Word von Qualicen. Die Beispiele selbst stammen aus einer englischen Anforderungsspezifikation für ein Softwaresystem.

Im ersten Beispiel schreibt der Autor von „other files“, ohne explizit zu spezifizieren, welche Dateien hier gemeint sind, oder wie der Bezug zu den Attributwerten genau ist. Das ist jedoch eine wichtige Information für eine Entwicklerin oder einen Tester. Eine gute Reviewerin würde das vermutlich bemängeln. Schneller und unkomplizierter geht es aber automatisch. Das Word-Plugin detektiert das Problem als „Imprecise Phrase“.

Im nächsten Beispiel spezifiziert die Autorin eine komplizierte Anforderung in einem langen und komplexen Satz. Einfacher zu lesen wären in diesem Fall mehrere kürzere Sätze. So wie die Anforderung jetzt formuliert ist, besteht die Gefahr, dass der Entwickler einen Teil der Anforderung überliest. Schnell schleichen sich so Fehler in ein System ein. Lange und komplizierte Sätze werden aber auch von automatischen Werkzeugen ziemlich zuverlässig gefunden.

Ein letztes Beispiel ist die Prüfung von Satzmustern. Satzmuster sind Schablonen, nach denen Sätze konstruiert werden sollen. Nicht immer sind Satzmuster sinnvoll. Wenn sie jedoch genutzt werden, haben sie den Vorteil, dass die Texte klar strukturiert und meist gut lesbar sind. Ein Beispiel für ein Satzmustersystem ist das EARS-Template. Das EARS-Template erlaubt im Wesentlichen fünf Satzstrukturen. Darunter zum Beispiel:

  • The <system name> shall <system response>, oder
  • When <optional preconditions> <trigger>, the <system> shall <system response>

Werden solche Satzmuster genutzt, ist es sinnvoll die Einhaltung gleich beim Schreiben zu überprüfen. Auch das ist eine Aufgabe, die automatische Werkzeuge zuverlässig erledigen und so Autoren und Reviewer entlasten. In dem Beispiel unten habe ich die inhaltlich gleiche Anforderung in zwei Varianten aufgeschrieben. Einmal im EARS Stil (siehe zweites Muster oben), einmal nicht. Das Word-Plugin detektiert das Problem im zweiten Fall und zeigt einen Hinweis an.

Fazit

Technische Texte müssen in erster Linie korrekt und verständlich sein. So, wie wir Werkzeuge für Rechtschreib- und Grammatikprüfungen nutzen, können wir auch die Verständlichkeit und die Einhaltung von Schreibregeln automatisch prüfen. Am besten geschieht das schon während dem Schreiben. Probleme lassen sich dann schnell ausbauen und die Reviewer werden sich bei Ihnen bedanken!

Über den Autor

Maximilian Junker hat im Bereich Software Engineering an der Technischen Universität München promoviert. Er ist Mitgründer und Geschäftsführer bei der Qualicen GmbH. Seit sechs Jahren berät er Requirements Engineers bei der Verbesserung ihrer Anforderungsdokumente. Zu Themen rund um Requirements Engineering hält er regelmäßig Vorträge für Forschung und Industrie.

@maximilianjun

 

Weitere Tool-Berichte: 

Like it? Share it! Spread the Word...