Eine Software Dokumentation schreiben

PDF download PDF herunterladen
PDF download PDF herunterladen

Eine gute Software-Dokumentation, egal ob ein Pflichtenheft für Programmierer und Tester, ein technisches Dokument für interne Benutzer oder Software-Handbücher und Hilfedateien für die Endbenutzer, hilft der Person, die mit der Software arbeitet, ihre Eigenschaften und Funktionen zu verstehen. Eine gute Software-Dokumentation ist spezifisch, präzise und relevant, sie bietet der Person alle wichtigen Informationen an, um die Software zu benutzen. Im Folgenden findest du eine Anleitung zum Schreiben von Software-Dokumentationen für technische Anwender und Endbenutzer.

Methode 1
Methode 1 von 2:

Eine Software-Dokumentation für technische Anwender schreiben

PDF download PDF herunterladen
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-460px-Write-Software-Documentation-Step-1.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-728px-Write-Software-Documentation-Step-1.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Pflichtenhefte dienen als Referenzhandbücher für die Designer der Benutzeroberfläche, die Programmierer, die den Code schreiben und die Teste, die überprüfen, ob die Software wie vorgesehen funktioniert. Die genauen Informationen hängen von dem Programm, das in Frage kommt, ab, aber könnten folgendes enthalten:
    • Schlüsseldateien innerhalb der Anwendung. Das könnte Dateien, die vom Entwicklungsteam erschaffen wurden, Datenbanken auf die während der Benutzung des Programmes zugegriffen wird und Dienstprogramme von Drittanbietern umfassen.
    • Funktionen und Unterfunktionen. Dies beinhaltet eine Erklärung was die jeweiligen Funktionen tun, inklusive deren In- und Ausgangsleistung.
    • Programmvariablen und -konstanten und wie diese in der Applikation angewandt werden.
    • Die allgemeine Programmstruktur. Für eine Disk-basierte Applikation bedeutet dies die Beschreibung der individuellen Programmm-Module und Bibliotheken, wohingegen bei der Web Applikation beschrieben wird, welche Seiten welche Files nutzen.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-460px-Write-Software-Documentation-Step-2.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-728px-Write-Software-Documentation-Step-2.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Je mehr technische Dokumentation am Anfang in den Programm-Quellcode eingebunden wird, desto einfacher wird es diese mit dem Code zusammen zu aktualisieren und zu pflegen, sowie auch verschiedene Versionen der ursprünglichen Version zu dokumentieren. Eine Dokumentation innerhalb des Quellcodes sollte zumindest den Zweck der Funktionen, Programmverzeichnisse, Variablen und Konstanten erklären.
    • Wenn der Quellcode besonders lang ist, dann kann die Dokumentation in Form von einer Hilfedatei zur Verfügung stehen, die indexiert werden und dann mit Schlüsselwörtern durchsucht werden kann. Dies ist besonders von Vorteil bei Anwendungen, in denen die Programmlogik über mehrere Seiten aufgeteilt ist und eine Reihe von zusätzlichen Dateien enthält, wie es bei bestimmten Web-Anwendungen der Fall ist.
    • Einige Programmiersprachen, wie Java und .NET Framework (Visual Basic, C#), haben ihren eigenen Standard für die Dokumentation innerhalb des Codes. In diesen Fällen solltest du die Standards wie viel Dokumentation im Quellcode vorhanden sein sollte befolgen.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-460px-Write-Software-Documentation-Step-3.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-728px-Write-Software-Documentation-Step-3.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Bis zu einem gewissen Grad wird dies durch die verwendete Sprache, in der der Code geschrieben wurde, sei es in C++, C# , Visual Basic, Java oder PHP, bestimmt, da es besondere Anwendungen für diese und andere Sprachen gibt. In anderen Fällen wird die Anwendung je nach Art der Dokumentation bestimmt.
    • Textverarbeitungsprogrammen wie Microsoft Word sind für die Erstellung von getrennten Textdateien der Dokumentation ausreichend, solange die Dokumentation kurz und einfach ist. Für lange, komplexe Textdateien bevorzugen viele technische Autoren eine Dokumentationsanwendung wie z.B. Adobe FrameMaker.
    • Hilfedateien, um den Quellcode zu dokumentieren können mit jedem Autorenwerkzeug für Online-Hilfen, wie z.B. RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare oder HelpLogix produziert werden.
    Werbeanzeige
Methode 2
Methode 2 von 2:

Eine Software-Dokumentation für Endbenutzer schreiben

PDF download PDF herunterladen
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-460px-Write-Software-Documentation-Step-4.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-728px-Write-Software-Documentation-Step-4.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Auch wenn der sachliche Grund eine Software zu dokumentieren die Hilfe für Anwender, um die Software zu verstehen, ist, gibt es andere Gründe, wie z.B. die Unterstützung bei der Vermarktung der Software, Verbesserung des Firmenimage und vor allem die Reduzierung der technischen Support-Kosten. In einigen Fällen ist eine Dokumentation notwendig, um bestimmten Verordnungen oder anderen gesetzlichen Anforderungen nachzukommen.
    • Software-Dokumentation sollte jedoch auf keinen Fall ein Ersatz für schlechtes Design der Benutzeroberfläche sein. Wenn ein Anwendungsbildschirm Unmengen von Dokumentation zur Erklärung erfordert, dann ist es besser das Design der Benutzeroberfläche in etwas Intuitiveres zu ändern.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-460px-Write-Software-Documentation-Step-5.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-728px-Write-Software-Documentation-Step-5.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    In den meisten Fällen haben die Anwender außerhalb ihrer Aufgaben, die sie mit der Anwendung erledigen, weniger Wissen über Computer. Es gibt mehrere Möglichkeiten, um ihre Bedürfnisse in deiner Dokumentation zu bestimmen.
    • Schaue dir die Stellenbezeichnung der voraussichtlichen Benutzer an. Ein Systemadministrator ist wahrscheinlich ein Experte bei einer Reihe von Software-Anwendungen, während ein Angestellter der Datenerfassung wahrscheinlich nur die Anwendung kennt, die er oder sie derzeit verwendet, um die Daten einzugeben.
    • Schaue dir die Benutzer selbst an. Auch wenn Stellenbeschreibungen normalerweise angeben, was Leute tun, gibt es erhebliche Unterschiede in der Verwendung von Berufsbezeichnungen innerhalb verschiedener Unternehmen. Durch Gespräche mit den voraussichtlichen Anwendern kannst du ein Gefühl dafür bekommen, ob deine Eindrücke, die du durch die Stellenbezeichnungen hast, korrekt sind oder nicht.
    • Schaue dir vorhandene Dokumentationen an. Dokumentationen für frühere Versionen einer Software, sowie das Pflichtenheft können dir einen Hinweis darauf geben, was der Benutzer wissen muss, um die Software zu verwenden. Denke daran, dass die Endbenutzer jedoch nicht so stark daran interessiert sind, was das Programm alles tun kann, sondern eher daran interessiert sind, was es für sie tun kann.
    • Identifiziere die Aufgaben, die für ihre Arbeit benötigt werden und welche Aufgaben erledigt werden müssen, bis diese Aufgaben erledigt werden können.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-460px-Write-Software-Documentation-Step-6.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-728px-Write-Software-Documentation-Step-6.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Software-Dokumentation können in 2 verschiedenen Formaten strukturiert werden, als Referenzhandbuch oder als Benutzerhandbuch. Manchmal ist die Kombination aus diesen beiden der beste Ansatz.
    • Ein Referenzhandbuch widmet sich den Möglichkeiten einer Softwareanwendung (Button, Registerkarten, Felder und Dialogfelder) und deren Funktionsweise. Viele Hilfedateien sind in diesem Format geschrieben, besonders kontextsensitive Hilfe, die ein relevantes Thema angezeigt, sobald ein Benutzer auf die Hilfe-Schaltfläche innerhalb eines bestimmten Bildschirms klickt.
    • Ein Benutzerhandbuch erklären wie die Software benutzt werden muss, um eine bestimmte Aufgabe durchzuführen. Benutzerhandbücher sind oft als gedruckte Handbücher oder PDF-Dokumente formatiert, obwohl einige Hilfe-Dateien auch eine Erklärung zur Durchführung bestimmter Aufgaben enthalten. (Diese Hilfethemen sind in der Regel nicht kontextsensitive, obwohl sie Links zu den Themen enthalten können.) Benutzerhandbücher haben häufig die Form von Tutorials mit einer Zusammenfassung der Aufgabe zu Beginn und eine Anweisung mit nummerierten Schritten mit einer Zusammenfassung der Aufgaben bei der Einführung und Anweisungen zur Durchführung in nummerierten Schritten.
  4. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-460px-Write-Software-Documentation-Step-7.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-728px-Write-Software-Documentation-Step-7.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Software-Dokumentation für Endbenutzer können eine oder mehrere von vielen Formen annehmen: Gedruckte Handbücher, PDF-Dokumente, Hilfedateien oder Online-Hilfen. Jede Form ist darauf ausgelegt dem Benutzer die Verwendung aller Funktionen des Programms zu erklären, egal ob in der Form eines Tutorials oder einer Anleitung; beim Fall von Hilfedateien und Online-Hilfen können Videos, sowie Text und Grafiken eingebunden werden.
    • Hilfedateien und Online-Hilfen sollten indexiert und nach Schlüsselwörtern durchsuchbar sein, damit Benutzer die Informationen, die sie suchen, schnell finden können. Auch wenn Autorenwerkzeuge für Online-Hilfen den Index automatisch generieren können, ist es oft besser, den Index mit Begriffen, nach denen die Benutzer suchen, manuell zu erstellen.
  5. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-460px-Write-Software-Documentation-Step-8.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-728px-Write-Software-Documentation-Step-8.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Gedruckte oder PDF-Benutzerhandbücher können abhängig von der Länge und Komplexität mit einem Textverarbeitungsprogramm wie Word oder einem anspruchsvollen Text-Editor wie FrameMaker geschrieben werden. Hilfe-Dateien können mit Autorenwerkzeugen für Online-Hilfe RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer geschrieben werden.
    Werbeanzeige

Tipps

  • Der Text sollte so arrangiert werden, dass er einfach zu lesen ist, indem die Grafiken so nah an dem Text, wie möglich, platziert werden, wenn er auf diese verweist. Teile die Dokumentation logisch in Bereiche und Themen auf. Jeder Abschnitt oder jedes Thema sollte ein einzelnes Problem, sei es eine einzelne Programmfunktion oder Aufgabe, behandeln. Verwandte Frage können mit "Siehe auch" adressiert oder bei Bedarf mit Hyperlinks angesprochen werden.
  • Jede der oben aufgeführten Dokumentationsanwendungen kann mit einer Anwendung zum Erstellen von Screenshots, wie Snagit, ergänzt werden, wenn die Dokumentation eine Reihe von Screenshots erfordert. Wie bei anderen Dokumentationen sollten Screenshots eingebunden werden, um zu erklären, wie die Software funktioniert, nicht um den Benutzer zu verwirren.
  • Der Ton ist vor allem beim Schreiben einer Software-Dokumentation für Endbenutzer besonders wichtig. Sprich die Benutzer mit "Sie" an, statt in der dritten Person mit "Benutzer".
Werbeanzeige

Was du brauchst

  • Software-Dokumentationsanwendung/Autorenwerkzeug für Online-Hilfen
  • Anwendung zum Erstellen von Screenshots

Referenzen

  1. http://www.softwaredocumentation.info/DocumentingSoftware.aspx
  2. http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm
  3. http://www.techscribe.co.uk/ta/how-to-write-instructions.htm
  4. Rodney Ruff, Omaha, NE; experience as technical writer/help file author since 1997

Über dieses wikiHow

In anderen Sprachen
Diese Seite wurde bisher 68.525 mal abgerufen.

War dieser Artikel hilfreich?

Werbeanzeige