Grundprinzipien einer Architektur-Dokumentation: Erkläre

Mischa Sameli, Geschäftsführer & Leiter Entwicklung

Erkläre Deine Notation: Solange Du die Bedeutung von Symbolen offen lässt, bleibt Spielraum für Interpretation, Mehrdeutigkeit und Missverständnis. Du solltest es den Lesern möglichst einfach machen, die Bedeutung von Symbolen und Diagrammen so zu verstehen, wie Du es gemeint hast.

Da wird man von einem Kollegen gebeten, kurz einen Blick auf ein Diagramm zu werfen, was man freundlicherweise nach guter alter Schulmanier tut (Erklären Sie in maximal 5 Sätzen, was Sie auf dem Bild sehen), und was erntet man? Kommentare wie „nicht ganz" oder „könnte man so sehen, ja" und gemeint ist aber „Ich habe mir folgendes dabei gedacht: …". Gedacht, schön und gut, aber wie zum Henker soll ich merken, was Du gedacht hast, aber leider vergessen hast zu erwähnen? Das ganze Leben ist ein Quiz, trällert Hape immer so schön, aber hier hört der Spass auf. Also anstatt lange zu erklären, was man eigentlich gemeint hat, sollte man besser die Zeit in die Verbesserung des Diagramms investieren. Oder anders formuliert: korrigieren statt argumentieren.