Grundprinzipien einer Architektur-Dokumentation: Lesersicht

Mischa Sameli, Geschäftsführer & Leiter Entwicklung

Wenn man ein Konzept schreibt, das vermutlich rund 50 Seiten umfassen wird, lohnt es sich vermutlich, ein paar grundlegende Gedanken über den Aufbau eines solchen Dokuments anzustellen. Was ich so gefunden habe zu diesem Thema habe, möchte ich in einer kleinen täglichen Serie hier festhalten, damit auch über die einzelnen Punkte diskutiert werden kann.

Schreibt aus der Sicht der Leser

Dokumente werden häufiger gelesen als geschrieben. Achtet darauf, dass eure Leser sie auch verstehen können. Du bist als Autor Dienstleister am Leser. Verwende auch das Vokabular der Leserschaft. Erkläre zentrale und für das Verständnis wesentliche Begriffe in einem Glossar. Mit diesem Leitsatz kommt man natürlich schnell in einen Konflikt, wenn man sein Zielpublikum nicht genau kennt, oder aber ein sehr gemischtes Zielpublikum vorhanden ist. Benutzt mach Fachsprache, steigen Themen-Laien bereits bei der Einleitung aus – Glossar hin oder her. Wird man geschwaflig oder allzu oberflächlich, verliert man bei Fachleuten das ansehen. Ich würde spontan zu mehreren Dokumenten tendieren: ein Konzept für die Allgemeinheit und technische Lösungskonzepte für Fachleute.