Softwaredokumentation

Sicherlich hast du schon einmal einen Code geschrieben, von dem du wolltest, dass ihn auch deine Kollegen nachvollziehen können. Das ist zum Beispiel wichtig, wenn diese Teile davon wiederverwenden möchten.

Doch nicht nur andere Entwickler benötigen eine Beschreibung der Funktionsweise von Software, sondern auch Benutzer. Diese Erklärungen werden Softwaredokumentation genannt. Doch wie verfasst du am besten Dokumentationen für unterschiedliche Zielgruppen? Welche Arten von Beschreibungen benötigst du und welche Werkzeuge stehen dir dafür zur Verfügung?

simpleclub erklärt dir verschiedene Typen von Softwaredokumentation je nach Zielgruppe und wie du sie mithilfe von Dokumentationswerkzeugen erstellt.

Softwaredokumentation einfach erklärt

Kyra arbeitet zusammen mit anderen an einem Softwareprojekt. Viele Teile, die sie schreibt, verwenden ihre Kollegen wieder. Es ist daher wichtig, dass sie ihren Code genau dokumentiert. Das bedeutet zum Beispiel, dass sie zu jeder Methode die benötigten Parameter, Rückgabewerte und durchgeführten Berechnungen exakt beschreibt. Ihre Kollegen wissen somit sofort, was die Methode macht und wie sie funktioniert. Damit können sie sie verwenden, ohne sich den Quellcode genauer ansehen zu müssen.

Sobald die Software fertig ist, muss sie natürlich auch von Endanwendern verstanden und benutzt werden können. Die Beschreibung der Software für Benutzer ist auch eine Art der Dokumentation, bei der Kyra und ihr Team die Funktionsweise erklären. Dies kann zum Beispiel klassisch in Form eines Handbuchs passieren.

Definition Softwaredokumentation

Erklärung Softwaredokumentation

Wie oben bereits angedeutet wurde, gibt es zwei große Arten von Dokumentationen:

• Dokumentation für andere Entwickler, auch Programmiererdokumentation genannt
• Dokumentation für Endanwender, auch als Benutzerdokumentation bezeichnet

Es gibt jedoch auch noch viele weitere Arten von Softwaredokumentation, die sich an kleinere Zielgruppen richten.

Programmiererdokumentation

Die Programmiererdokumentation beschreibt den Quellcode der Software. Sie wird soweit wie möglich direkt in diesen eingearbeitet, zum Beispiel durch speziell formatierte Kommentare. Diese Kommentare können durch Dokumentationswerkzeuge erkannt und in eine besser lesbare Form übertragen werden. Das können zum Beispiel HTML-Dokumente sein, die auf der Website der Entwickler veröffentlicht werden. Vermutlich sind dir diese schon einmal begegnet, wenn du Beschreibungen von Methoden, die du noch nicht kanntest, gesucht hast. Du lernst weiter unten ausgewählte Dokumentationswerkzeuge kennen.

Abbildungen oder andere Arten von Erklärmaterialien, die nicht direkt in den Quelltext eingearbeitet werden können, werden durch zusätzliche Dateien zur Verfügung gestellt.

Grundsätzlich können zwei Arten von Programmiererdokumentation unterschieden werden:

• Innere Dokumentation: Beschreibung des Quellcodes einer Software, um diese weiterzuentwickeln.
• Äußere Dokumentation: Beschreibung für Entwickler, die eine Programmierschnittstelle zur Software nutzen wollen.

Benutzerdokumentation

Die Benutzerdokumentation beschreibt die Funktionsweise von Software für Endanwender. Dies kann auf vielfältige Art und Weise geschehen:

• Kontextsensitive Hilfe: Während der Benutzung der Software wird Hilfe angezeigt, die zum aktuellen Schritt passt. Beispielsweise durch Tipps in Form von Text oder kurzen Videos, die auftauchen, sobald sich der Mauszeiger über einen bestimmten Button befindet.
• Handbuch: Zur Software wird ein zusätzliches Handbuch ausgeliefert. Das kann einerseits klassisch analog oder auch als Online-Hilfe bereitgestellt werden.
• Assistenten: Es stehen virtuelle Assistenten zur Verfügung, die auf Fragen des Users antworten können. Oft wird dies durch eine eingebaute Chat-Funktion umgesetzt.
• Guided Tours: Verwendet ein User das erste Mal eine Software, wird er durch eine festgelegte Reihenfolge an Funktionen geführt. So lernt er direkt am Anfang die Grundlagen des Programms kennen.

Eine gute Benutzerdokumentation soll neben der Erklärung der Funktionsweise auch folgende Punkte umfassen:

• Ratschläge zur Problembehandlung
• Einen Bereich mit häufig gestellten Fragen (FAQ) und Antworten darauf
• Glossar mit Erklärungen zu Fachbegriffen

Weitere Dokumentationsarten

Neben der Programmierer- und Benutzerdokumentation gibt es noch weitere Arten der Softwaredokumentation. Sie zielen auf kleinere Anwendungsbereiche und Zielgruppen ab.

Beispiele Dokumentationswerkzeuge

Dokumentationswerkzeuge erstellen automatisch Softwaredokumentation in gut lesbaren Formaten. Es gibt verschiedene Werkzeuge für unterschiedliche Programmiersprachen.

Im Wesentlichen funktioniert ein Dokumentationswerkzeug folgendermaßen: Es entnimmt Informationen aus Objekten, die während des Entwicklungsprozesses entstanden sind, wie z. B. Quellcode-Dateien oder UML- Diagramme. Diese Informationen können beispielsweise in Form von speziell formatierten Kommentaren im Code vorliegen. Das Dokumentationswerkzeug überführt die Informationen in separate Dateien und bereitet sie so auf, dass sie für Menschen gut lesbar sind.

Javadoc

Javadoc ist das Standard-Dokumentationswerkzeug für die Programmiersprache Java. Es generiert aus speziell gekennzeichneten Kommentaren im Quelltext HTML-Dateien, die übersichtlich formatierte Informationen zu den beschriebenen Teilen des Codes beinhalten.

Ein Kommentar im Quelltext, welches durch Javadoc erkannt wird, beginnt mit /** und endet mit /. Alle Zeilen dazwischen werden mit * gekennzeichnet. Zusätzlich können bestimmte Tags wichtige Informationen kennzeichnen, die Javadoc besonders hervorhebt: Beispielsweise leitet „@param" die Beschreibung eines Parameters einer Methode ein, „@returns*" dagegen die des Rückgabewerts.

Ein Kommentar für eine Methode, der für Javadoc lesbar ist, steht unmittelbar vor der Methodensignatur und kann folgendermaßen aussehen:

Doxygen

Doxygen wird meistens für die Programmiersprachen C oder C++ genutzt. Es wird aber auch für die Sprachen Java, Pyhon oder eingeschränkt für PHP verwendet.

Ähnlich wie bei Javadoc werden auch hier speziell formatierte Kommentare als Grundlage genommen. Es können allerdings neben HTML-Dateien noch andere Dateien, wie z. B. PDF- oder Markdown-Dateien generiert werden. Zudem wird neben der Umwandlung der Kommentare auch noch ein Überblick über den Aufbau des Programms sowie die Rollen verschiedener Dateien und Variablen erzeugt.

Kommentare, die von Doxygen verwendet werden sollen, sind wie bei Javadoc in /** und ***/** eingefasst. Außerdem existieren auch spezielle Tags, die üblicherweise statt mit @ mit \ eingeleitet werden.

Dasselbe Ergebnis wie bei Javadoc wird durch Doxygen und folgenden C-Code erzeugt:

Sphinx

Sphinx wird als Dokumentationswerkzeug für die Programmiersprache Python verwendet. Es wandelt Kommentare im Quelltext in HTML-, PDF- oder andere Dateien um. Die Besonderheit bei Sphinx ist, dass es auch mathematische Symbole darstellen kann.

Beim folgenden Python-Code generiert Sphinx wieder dieselbe Ausgabe wie beim Beispiel von Javadoc.

Bei Sphinx werden die entsprechenden Kommentare mit je drei Anführungszeichen ("""") begonnen und geschlossen. Der dazwischenstehende Text wird nach den Regeln von reStructuredText verfasst. Dies ist eine sogenannte Auszeichnungssprache, bei der der Verfasser Layout-Anweisungen direkt in den Text schreibt. Beispielsweise führt -------------- (Abfolge von Minus-Symbolen) einen neuen Abschnitt ein, ohne selbst im erzeugten Dokument aufzutauchen.

Zusammenfassung Softwaredokumentation

Bei einer Softwaredokumentation handelt es sich um die Beschreibung der Funktionsweise von Software für unterschiedliche Zielgruppen. Typischerweise wird zwischen Programmierer- und Benutzerdokumentation unterschieden.

Während die Benutzerdokumentation auf vielfältige Weise z. B. in Form von Guided Tours oder Chat-Assistenten bereitgestellt wird, wird die Programmiererdokumentation meist direkt in den Code eingebaut. Dabei werden häufig speziell formatierte Kommentare verwendet, die von Dokumentationswerkzeugen erkannt und in ein besser lesbares Format übertragen werden.

Es gibt für unterschiedliche Programmiersprachen verschiedene Dokumentationswerkzeuge. Beispiele für gängige Werkzeuge sind

• Javadoc für Java
• Doxygen für C oder C++
• Sphinx für Python

Es kann noch zwischen weitere Arten von Dokumentation für kleinere Zielgruppen unterschieden werden, z. B. Installations- oder Methodendokumentation.