+
−\section{Dokumentation}
+
−
+
−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.
+
−
+
−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.
+
−
+
−Meine Dokumentation enth�lt somit zum gr��ten Teil die hier aufgez�hlten Informationen:
+
−\begin{itemize}
+
−  \item Grunds�tzliche Informationen zur technischen Struktur des Programms
+
−  \item Programmdesign-Prinzipien
+
−  \item Kurzbeschreibung der einzelnen Programmteile und genauere Erl�uterungen zu einzelnen Funktionen
+
−  \item Tipps, Hinweise und Anmerkungen aller Art
+
−  \item Konkrete Anleitungen falls n�tig (Bei der Translator-Datenbank ist das zum Beispiel: ``So f�ge ich eine Sprache hinzu'')
+
−\end{itemize}
+
−
+
−Was f�r mich nicht, oder nur in geringem Ma�e, in der Dokumentation vertreten sein sollte, sind:
+
−\begin{itemize}
+
−  \item Zu detaillierte Informationen
+
−  \item Variablen-, Klassen-, Dateinamen und �hnliches
+
−\end{itemize}
+
−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.
+
−
+
−
+
−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.
+
−
+
−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.
+
−
+
−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.
+
−
+
−
+
−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.
+
−
+
−