Wenn ich Software-Dokumentationen oder Konzepte lese, bekomme ich oft das Gefühl, dass mir einige Informationen fehlen, um das Geschriebene in die Tat umzusetzen. Ich spüre das Beamtendeutsch in den einzelnen Sätzen. Ich weiß nicht, ob eine beschriebene Aktion eine ist, die ich ausführen sollte oder sie eine ist, die automatisch, unabhängig von mir, geschieht. Leute denken leider viel zu oft, dass es sich gut anhört, wenn man möglichst unverbindlich schreibt, was "geschehen soll".
Dabei gibt einen ganz einfachen Trick einen Text so zu schreiben, dass jeder weiß, wann man Aktivitäten als Leser ausführen muss und wann nicht.
Nun erstmal ein paar Beispiele aus dem realen Leben:
- "Daher muss der git-Workflow an die derzeitigen Entwicklungsbedingungen angepasst werden."
- "UI-Layer muss immer zusammen mit CM-Branch released werden"
- "Die Build-Artefakte werden in Repositories abgelegt (z.B. Artifactory)"
- "Änderungen werden über Jenkins mit einem privilegierten User durchgeführt."
- "Es muss sehr genau geprüft werden, wie sich das Webserver-Caching auf die Performance auswirkt."
Die Sätze lassen mich immer mit Fragen im Kopf dastehen:
Der Git-Workflow passt sich nicht von alleine an die derzeitigen Entwicklungsbedingungen an. Wer macht es?
Der UI-Layer releast sich nicht von alleine immer zusammen mit dem CM-Branch. Wer macht es?
Wer legt Build-Artefakte in Repositories ab?
Wer führt die Änderungen über Jenkins mit einem privilegierten User durch?
Wer prüft wie sich das Webserver-Caching auf die Performance auswirkt?
Wer macht das alles? Als Leser wissen wir das nicht.
Der Trick ist: Streicht das "werden" weg und schreibt den Satz nochmal.
Völlig automatisch lesen sich die oben genannten Sätze dann so:
- "Passe den git-Workflow an die derzeitigen Entwicklungsbedingungen an."
- "Release den UI-Layer immer zusammen mit dem CM-Branch."
- "Lege die Build-Artefakte in Repositories (z.B. Artifactory) ab."
- "Führe die Änderungen über Jenkins mit einem privilegierten User durch."
- "Prüfe sehr genau, wie sich das Webserver-Caching auf die Performance auswirkt."
Nun ist klar. It's your job! Der Leser muss die genannten Aktionen ausführen.
Natürlich kann auch sein, dass jemand anderes die Aktivitäten ausführen muss. Dann reicht es doch, denjenigen zu benennen. Etwa so:
- "Der Releasemanager passt den git-Workflow an die derzeitigen Entwicklungsbedingungen an."
- "Jenkins releast den UI-Layer immer zusammen mit dem CM-Branch automatisch."
- "Maven legt die Build-Artefakte in Repositories (z.B. Artifactory) ab."
- "Jenkins führt die Änderungen mit einem privilegierten User automatisch durch."
- "Das Skript prüft sehr genau, wie sich das Webserver-Caching auf die Performance auswirkt."
So einfach kann es sein. Dadurch werden wir alle besser verstehen, wer oder was gemeint ist. Wir werden nicht mehr untätig vor dem PC sitzen und uns fragen: Hö? Wer macht das nun?
