Wenn, dann vernünftig: Tipps für eine technische Dokumentation in SAP
Die technische Dokumentation ist ein leider oft stiefmütterlich behandeltes Thema. Meist wird sie gegen Ende des Projekts angefertigt, wenn es wichtiger erscheint, die letzten Prozent des Projekts erfolgreich umzusetzen. Zudem existiert unterbewusst die Annahme, dass die Dokumentation erstmal keinen Nutzen für den Kunden bietet, da sie keine der funktionalen Anforderungen des Projekts umsetzt. Das sind jedoch Trugschlüsse, die bestenfalls als Ausrede dienen.
Eine technische Dokumentation ist ebenso Teil des Projektergebnisses, wie z.B. jede Methode einer Klasse oder jede Oberfläche, die die gewünschte Funktionalität realisiert.
Also, wie schreibe ich eine gute technische Dokumentation, was ist wichtig, was unerlässlich?
Die Antwort ist wie sooft: “Das kommt drauf an.” Projekte unterscheiden sich voneinander und genauso ist es mit der technischen Dokumentation. Es gibt keinen Standard. Sie muss dem Projekt genügen bzw. sich an ihm orientieren. Komplexe technische Finesse erfordert meist auch eine ausführliche Dokumentation; ist der technische Anteil eines Projekts gering und verhältnismäßig simpel, kann das Dokument auch ruhig schmaler ausfallen. Bei diesen Überlegungen ist zu empfehlen, den eigentlichen Grund vor Augen zu haben.
Die technische Dokumentation und ihr Ziel
Ziel der technischen Dokumentation ist, dass im Nachhinein nachvollzogen werden kann, was während des Projekts aus technischer Sicht geschah. Sie dient dazu, festzuhalten, welche Objekte im Laufe des Projekts angefasst wurden. Zudem bietet es sich an, genaue Beschreibungen der Änderungen bzw. Neuentwicklungen und die Intention dahinter darzulegen und komplexe Bestandteile zu erklären. Zu einem späteren Zeitpunkt soll ein Entwickler – egal ob neu im Thema oder vorheriger Mitarbeiter in dem Projekt – die Möglichkeit haben, sich mithilfe der Dokumentation einen Überblick über die Entwicklung zu verschaffen und möglichst schnell und komfortabel die technischen Details (wieder) zu verstehen.
Hier sind einige bewährte Hilfsmittel und Tipps für das Anfertigen einer technischen Dokumentation:
Dokument-Historie
Immer hilfreich für Dokumente, die weitere Versionen erhalten werden, ist ein kurzer Verlauf über die Lebenszeit des Dokuments. Direkt nach dem Inhaltsverzeichnis ist diese Information gut aufgehoben. Sie können die Historie auch anreichern mit einer Spalte für konkrete Änderungsnotizen, je nach Bedarf.
Die Vorgängerversion des Dokuments ist bei einer Änderung zu archivieren und die neue Version mit einer höheren Versionsnummer und/oder dem aktuellen Datum zu versehen. Das kann beispielsweise so aussehen:
Objektliste
Es ist praktisch, eine strukturierte Liste zu Beginn des Dokuments einzufügen, welche alle Objekte beinhaltet, die erzeugt, geändert oder gelöscht wurden. Auch hier können Sie beliebig Spalten hinzufügen, die z.B. den Grund der Löschung erklären. Richten Sie sich nach dem Umfang des Projekts.
Inline-Dokumentation
Wurden Objekte angefasst, die Coding beinhalten, ist eine vernünftige Inline-Dokumentation auf alle Fälle zu empfehlen. Das Vorgehen hierbei ist in diesem Artikel beschrieben.
Bei z.B. Datenelementen ist so etwas leider nicht möglich, hier hilft die obige Objektliste.
Diagramme
Nutzen Sie Diagramme, um Übersicht zu schaffen und komplexe Sachverhalte anschaulich darzustellen. Schöpfen Sie aus der vollen Palette der UML-Modellierung, der Leser wird es Ihnen danken.
Manche Prozesse sind womöglich schon zu Beginn des Projekts in einem DV-Konzept abgebildet. Sobald Sie aber das Gefühl haben, dass das Diagramm dem Leser an dieser Stelle helfen wird, kopieren Sie es, so viel Redundanz darf sein.
Klassendiagramme empfehlen sich beispielsweise zu Beginn, bevor Sie in die Logik einzelner Methoden abtauchen.
Funktionalitäten beschreiben
Um dem Leser verständlich zu machen, was im Coding wie und warum getan wurde, genügen nicht immer Kommentare im Quellcode selbst. Auch nicht alles ist verständlich mit Schaubildern und Stichpunkten zu erklären. Nutzen Sie die technische Dokumentation, um – wenn nötig – komplexe Funktionalität zu beschreiben. Schrecken Sie nicht vor Fließtext in Maßen zurück!
Zusatz: Orthographie
Die folgenden Ausführungen beziehen sich nicht speziell auf eine technische Dokumentation, sondern auf das gesamte geschriebene Wort. In IT-bezogenen Dokumenten finden sich diese Fehler jedoch sehr häufig, da hier Fachbegriffe und Formulierungen in Deutsch und Englisch geballt und gemischt auftreten. In Business-Dokumenten haben diese Fehler aber generell nichts zu suchen und wirken unprofessionell. Dennoch kommen sie immer wieder vor.
Die Sache mit dem Apostroph
Hier kann man schon durcheinanderkommen, daher kurz die am häufigsten falsch angewandten Regeln (unvollständig, aber für den Alltagsgebrauch hinreichend) zusammengefasst.
Der Plural wird NIE mit Apostroph gebildet, auch nicht im Englischen: “The Servers”, nicht “The Server’s”.
Der Genitiv im Englischen hat einen Apostroph, im Deutschen allerdings nicht. Endet das Wort auf auf “s”, wird in beiden Sprachen ein Apostroph ohne gefolgtes “s” angehängt. Ausnahme sind Eigennamen im Englischen: Hier wird auch auf endendes “s” ein “‘s” angehängt.
DE: “Ingos Blog”, “Lukas’ Artikel”, ßà EN: “Ingo’s blog”, “Lukas’s article”, “the friends’ book”
Ist ein Apostroph zu nutzen, dann nicht der französische Akzent neben der Fragezeichen-Taste, sondern der richtige über der Raute.
Zusammengesetzte Substantive
Zusammengesetzte Worte und Produktnamen aus mehreren Worten bestimmen den Alltag der IT. Oft verwechselt werden hier die deutsche und die englische Schreibweise.
Im Englischen werden zusammengesetzte Substantive in der Regel ohne Bindestrich geschrieben: “security policy”.
Im Deutschen hingegen ist das nicht erlaubt und verwirrt. Daher: “Sicherheitsrichtlinie”. Zur Übersichtlichkeit ist auch erlaubt, Bindestriche zu nutzen: “Ausnahmefehler-Behandlung”. Aber nie: “Ausnahmefehler Behandlung”.
Haben Sie noch wichtige Punkte, die Sie in einer technischen Dokumentation sehen möchten? Oder haben Sie noch Fragen zu diesem Thema? Gerne beantworte ich diese in den Kommentaren.