Eine gute Softwaredokumentation, sei es Spezifikationsdokumentation für Programmierer und Tester, technische Dokumente für interne Benutzer oder Handbücher und Hilfedateien für Endbenutzer, hilft Benutzern, die Merkmale und Funktionen der Software zu verstehen. Eine gute Dokumentation ist eine spezifische, klare und relevante Dokumentation mit allen Informationen, die der Benutzer benötigt. In diesem Artikel erfahren Sie, wie Sie Softwaredokumentationen für technische Benutzer und Endbenutzer schreiben.
Schritt
Methode 1 von 2: Softwaredokumentation für technische Benutzer schreiben
Schritt 1. Wissen Sie, welche Informationen Sie einschließen müssen
Das Spezifikationsdokument wird als Referenzhandbuch für Schnittstellendesigner, Programmierer, die Code schreiben, und Tester, die die Softwareleistung überprüfen, verwendet. Die Informationen, die eingeschlossen werden müssen, hängen vom erstellten Programm ab, können jedoch Folgendes umfassen:
- Wichtige Dateien in der Anwendung, z. B. vom Entwicklungsteam erstellte Dateien, Datenbanken, auf die während der Ausführung des Programms zugegriffen wird, und Anwendungen von Drittanbietern.
- Funktionen und Unterprogramme, einschließlich einer Erläuterung der Verwendung der Funktion/des Unterprogramms, Ein- und Ausgabewerte.
- Programmvariablen und Konstanten und wie sie verwendet werden.
- Gesamtprogrammstruktur. Bei laufwerkbasierten Programmen müssen Sie möglicherweise jedes Modul und jede Bibliothek beschreiben. Wenn Sie ein Handbuch für ein webbasiertes Programm schreiben, müssen Sie möglicherweise erklären, welche Dateien jede Seite verwendet.
Schritt 2. Entscheiden Sie, welche Dokumentationsebene vorhanden und vom Programmcode trennbar sein soll
Je mehr technische Dokumentation im Programmcode enthalten ist, desto einfacher ist es, diese zu aktualisieren und zu pflegen sowie die verschiedenen Versionen des Programms zu erklären. Die Dokumentation im Programmcode sollte mindestens die Verwendung von Funktionen, Unterprogrammen, Variablen und Konstanten umfassen.
- Wenn Ihr Quellcode lang ist, können Sie eine Dokumentation in eine Hilfedatei schreiben, die dann mit bestimmten Schlüsselwörtern indiziert oder durchsucht werden kann. Getrennte Dokumentationsdateien sind sinnvoll, wenn die Programmlogik auf mehrere Seiten aufgeteilt ist und Unterstützungsdateien enthält, wie z. B. eine Webanwendung.
- Einige Programmiersprachen (wie Java, Visual Basic. NET oder C#) haben ihre eigenen Codedokumentationsstandards. Befolgen Sie in solchen Fällen die Standarddokumentation, die im Quellcode enthalten sein muss.
Schritt 3. Wählen Sie das entsprechende Dokumentationstool aus
In einigen Fällen wird das Dokumentationswerkzeug durch die verwendete Programmiersprache bestimmt. Die Sprachen C++, C#, Visual Basic, Java, PHP und andere verfügen über eigene Dokumentationstools. Wenn nicht, hängen die verwendeten Tools von der erforderlichen Dokumentation ab.
- Ein Textverarbeitungsprogramm wie Microsoft Word eignet sich zum Erstellen von Dokumenttextdateien, sofern die Dokumentation prägnant und einfach ist. Um lange Dokumentationen mit komplexem Text zu erstellen, wählen die meisten technischen Redakteure ein spezielles Dokumentationstool wie Adobe FrameMaker.
- Hilfedateien zum Dokumentieren des Quellcodes können mit einem Supportdatei-Generatorprogramm wie RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare oder HelpLogix erstellt werden.
Methode 2 von 2: Softwaredokumentation für Endbenutzer schreiben
Schritt 1. Kennen Sie die geschäftlichen Gründe, die der Erstellung des Handbuchs zugrunde liegen
Während der Hauptgrund für die Softwaredokumentation darin besteht, den Benutzern zu helfen, die Anwendung zu verstehen, gibt es mehrere andere Gründe, die der Erstellung von Dokumentationen zugrunde liegen können, z Kosten. In einigen Fällen ist eine Dokumentation erforderlich, um Vorschriften oder andere gesetzliche Anforderungen zu erfüllen.
Dokumentation ist jedoch kein guter Ersatz für eine Schnittstelle. Wenn eine Anwendung für die Bedienung viel Dokumentation erfordert, sollte sie intuitiver gestaltet werden
Schritt 2. Kennen Sie die Zielgruppe der Dokumentation
Im Allgemeinen verfügen Softwarebenutzer über begrenzte Computerkenntnisse, die über die von ihnen verwendeten Anwendungen hinausgehen. Es gibt mehrere Möglichkeiten, ihren Dokumentationsbedarf zu decken:
- Achten Sie auf den Titel des Softwarebenutzers. Beispielsweise versteht der Systemadministrator im Allgemeinen verschiedene Computeranwendungen, während die Sekretärin nur die Anwendungen kennt, mit denen er Daten eingibt.
- Achten Sie auf Softwarebenutzer. Obwohl ihre Positionen in der Regel mit den ausgeführten Aufgaben kompatibel sind, können diese Positionen je nach Betriebsstätte unterschiedlich ausgelastet sein. Durch Interviews mit potentiellen Benutzern können Sie herausfinden, ob Ihre Einschätzung der Berufsbezeichnung richtig ist.
- Beachten Sie die vorhandene Dokumentation. Die Dokumentation und Spezifikationen der Softwarefunktionalität können zeigen, was Benutzer wissen müssen, um sie zu verwenden. Beachten Sie jedoch, dass Benutzer möglicherweise nicht daran interessiert sind, das "Innere" des Programms zu kennen.
- Wissen Sie, was es braucht, um eine Aufgabe zu erledigen, und was es braucht, bevor Sie sie erledigen können.
Schritt 3. Bestimmen Sie das geeignete Format für die Dokumentation
Die Softwaredokumentation kann in 1 oder 2 Formaten angeordnet sein, nämlich Nachschlagewerke und Handbücher. Manchmal ist die Kombination der beiden Formate eine gute Lösung.
- Referenzformate werden verwendet, um alle Softwarefunktionen wie Schaltflächen, Registerkarten, Felder und Dialogfelder und ihre Funktionsweise zu beschreiben. Einige Hilfedateien sind in diesem Format geschrieben, insbesondere solche, die kontextsensitiv sind. Wenn der Benutzer in einem bestimmten Bildschirm auf Hilfe klickt, erhält der Benutzer das entsprechende Thema.
- Das Handbuchformat wird verwendet, um zu erklären, wie man etwas mit der Software macht. Handbücher liegen im Allgemeinen im Druck- oder PDF-Format vor, obwohl einige Hilfeseiten auch Anweisungen für bestimmte Dinge enthalten. (Im Allgemeinen sind manuelle Formate nicht kontextsensitiv, können jedoch von kontextsensitiven Themen verlinkt werden). Handbücher haben in der Regel die Form eines Leitfadens mit einer Zusammenfassung der durchzuführenden Aufgaben in einer Beschreibung und einem Leitfaden, der in Schritten formatiert ist.
Schritt 4. Entscheiden Sie sich für die Art der Dokumentation
Softwaredokumentation für Benutzer kann in einem oder mehreren der folgenden Formate vorliegen: gedruckte Handbücher, PDF-Dateien, Hilfedateien oder Online-Hilfe. Jede Art von Dokumentation soll Ihnen zeigen, wie Sie die Funktionen der Software verwenden, egal ob es sich um eine Anleitung oder ein Tutorial handelt. Online-Dokumentation und Hilfeseiten können auch Demonstrationsvideos, Text und statische Bilder enthalten.
Online-Hilfe- und Supportdateien sollten mit Schlüsselwörtern indiziert und durchsuchbar sein, damit Benutzer die benötigten Informationen schnell finden können. Obwohl eine Anwendung zur Erzeugung von Hilfedateien einen Index automatisch erstellen kann, wird dennoch empfohlen, einen Index manuell mit häufig gesuchten Schlüsselwörtern zu erstellen
Schritt 5. Wählen Sie das entsprechende Dokumentationstool aus
Gedruckte Handbücher oder PDFs können je nach Länge und Komplexität der Datei mit einem Textverarbeitungsprogramm wie Word oder einem fortschrittlichen Texteditor wie FrameMaker erstellt werden. Hilfedateien können mit einem Hilfedatei-Erstellungsprogramm wie RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix oder HelpServer geschrieben werden.
Tipps
- Der Text der Programmdokumentation sollte so aufgebaut sein, dass er leicht lesbar ist. Platzieren Sie das Bild so nah wie möglich am entsprechenden Text. Gliedern Sie die Dokumentation logisch nach Abschnitten und Themen. Jeder Abschnitt oder jedes Thema sollte ein bestimmtes Problem beschreiben, sowohl die Aufgaben- als auch die Programmfunktionen. Verwandte Themen können mit Links oder Referenzlisten erläutert werden.
- Jedes der in diesem Artikel beschriebenen Dokumentationstools kann durch ein Screenshot-Erstellungsprogramm wie SnagIt ergänzt werden, wenn Ihre Dokumentation mehrere Screenshots erfordert. Wie bei jeder anderen Dokumentation sollten Sie auch Screenshots einfügen, um zu erklären, wie die App funktioniert, anstatt den Benutzer zu "locken".
- Es ist sehr wichtig, auf den Stil zu achten, insbesondere wenn Sie Softwaredokumentationen für Endbenutzer schreiben. Sprechen Sie Benutzer mit dem Pronomen „you“anstelle von „user“an.
