|
0
|
1 \section{Dokumentation}
|
|
|
2
|
|
|
3 Die Dokumentation von Programmen gehört ebenso wie das Programmieren selbst zur Softwareentwicklung dazu. Ich habe meine Anwendungen natürlich dokumentiert. Dies war für mich zuerst einmal eine eher neue Sache, da ich mich zwar mit der Notwendigkeit von Dokumentationen schon beschäftigt, aber noch keine selbst geschrieben hatte. Bei der technischen Umsetzung hielt ich mich an die Form die meine Vorgänger eingeführt hatten: Microsoft Word-Dokumente. Diese wandelte ich mittels OpenOffice.org in ein PDF um.
|
|
|
4
|
|
|
5 Mir war es wichtig, den Zusatzaufwand für die Dokumentation möglichst gering zu halten. Dieses Bestreben gründet zum Einen auf die allgemeine Erfahrung, dass Anwender keine Dokumentation lesen, und zum Anderen auf meine Überzeugung, dass nur der Quellcode selbst vollständig, aktuell und detailliert genug ist und deshalb vor allem er aussagekräftig und übersichtlich gemacht werden muss. Die Dokumentation sollte meiner Meinung nach nur als Ergänzung zum Quellcode gesehen werden. Sie ist jedoch trotzdem wichtig und notwendig um dem Entwickler schnell und direkt die grundlegende Logik und die nicht offensichtlichen Implementierungen des Programms offenzulegen. Des weiteren sollte sie dem Anwender Zusatzinformationen bieten, falls dieser ein Bedürfnis nach ihnen hat. Die Dokumentation für die beiden Personengruppen zu zweiteilen halte ich nicht unbedingt für sinnvoll, da auf diese Weise der Aufwand und die Redundanz steigt und bei Dokumentationen im Umfang von etwa 15 Seiten sollten die gesuchten Informationen noch recht einfach herauszufiltern sein.
|
|
|
6
|
|
|
7 Meine Dokumentation enthält somit zum größten Teil die hier aufgezählten Informationen:
|
|
|
8 \begin{itemize}
|
|
|
9 \item Grundsätzliche Informationen zur technischen Struktur des Programms
|
|
|
10 \item Programmdesign-Prinzipien
|
|
|
11 \item Kurzbeschreibung der einzelnen Programmteile und genauere Erläuterungen zu einzelnen Funktionen
|
|
|
12 \item Tipps, Hinweise und Anmerkungen aller Art
|
|
|
13 \item Konkrete Anleitungen falls nötig (Bei der Translator-Datenbank ist das zum Beispiel: ``So füge ich eine Sprache hinzu'')
|
|
|
14 \end{itemize}
|
|
|
15
|
|
|
16 Was für mich nicht, oder nur in geringem Maße, in der Dokumentation vertreten sein sollte, sind:
|
|
|
17 \begin{itemize}
|
|
|
18 \item Zu detaillierte Informationen
|
|
|
19 \item Variablen-, Klassen-, Dateinamen und ähnliches
|
|
|
20 \end{itemize}
|
|
|
21 Diese Informationen sorgen doch nur für einen allzu hohen Aufwand zum Aktuellhalten der Dokumente. Um auf derartige Zusatzinformationen aber nicht verzichten zu müssen, sollte man hier automatische Tools einsetzten. Ich habe an dieser Stelle das Programm \textit{Doxygen}\footnote{\textit{Doxygen} ist freie Software und kann von der Website http://doxygen.org heruntergeladen werden.} eingesetzt. Die Ergebnisse für Klassen waren dabei sehr gut, der größte Teil der sonstigen Informationen eher weniger brauchbar. Der Aufwand für Doxygen-Kommentare im Quellcode ist gering und dient der Übersichtlichkeit des Codes selbst. Das Generieren der Doxygen-Dokumentation erfordert dann nur einen Programmaufruf, der Rest erfolgt automatisch.
|
|
|
22
|
|
|
23
|
|
|
24 Wie man im Text sicher schon heraushören konnte, habe ich keine spezielle Anwenderdokumentation in Form von einem Handbuch oder ähnlichem geschrieben. Wir erinnern uns: Der Benutzer ließt dieselbige ja doch nicht.\footnote{Diese Grundannahme sollte mit ein wenig Humor verstanden werden.} Deshalb sollte man dem Anwender die zusätzlichen Informationen zum Programm auf eine Weise anbieten, sodass er möglichst wenig davon mitbekommt und schon gar keinen zusätzlichen Aufwand hat.
|
|
|
25
|
|
|
26 Diesen Überlegungen bin ich gefolgt und habe als erstes versucht meine Programmoberflächen möglichst natürlich zu gestalten. Der Benutzer sollte alles dort finden wo er es erwartet. Konzepte wie ``von links nach rechts'' bzw. ``von oben nach unten'', ``Gleiches zusammen'' und ``wiederkehrende Elemente'' machen hierbei den größten Teil aus. Alle meine Reports sollten ein \textit{Common Look'n'Feel}\footnote{Eine einheitliche Optik und Bedienung} haben.
|
|
|
27
|
|
|
28 Als wichtige Komponente, beim Anbieten von Zusatzinformationen ohne separates Handbuch, stellte sich dabei das Universalattribut \texttt{title} von HTML-Tags heraus. Mit ihm ist es möglich beliebigen Elementen einen Tooltip-Text zuzuweisen. Fährt man dann im HTML-Dokument mit dem Mauszeiger über das Element und verweilt kurz darauf, so öffnet sich ein kleines Informationsfenster mit dem hinterlegten Text. Diese Möglichkeit habe ich konsequent genutzt. So können zum Beispiel bei allen Tabellen durch überfahren der Spaltenüberschriften genauere Informationen zu den enthaltenen Werten gewonnen werden.
|
|
|
29
|
|
|
30
|
|
|
31 Für diejenigen Benutzer die trotz meiner Bemühungen um ein selbsterklärendes Oberflächendesign gerne die Dokumentation lesen möchten, habe ich diese auf den Startmasken der einzelnen Programme jeweils verlinkt. Ein Fragezeichen in der rechten oberen Ecke führt einheitlich zur Dokumentation in PDF-Form.
|
|
|
32
|
|
|
33
|
