Softwaredokumentation oder Quellcodedokumentation sind schriftlicher Text, der Computersoftware begleitet. Es entweder erklärt, wie es funktioniert, oder wie man es verwendet, und verschiedene Dinge Leuten in verschiedenen Rollen vorhaben kann.

Rolle der Dokumentation in der Softwareentwicklung

Dokumentation ist ein wichtiger Teil der Softwaretechnik. Typen der Dokumentation schließen ein:

1. Voraussetzungen - Behauptungen, die Attribute, Fähigkeiten, Eigenschaften oder Qualitäten eines Systems identifizieren. Das ist das Fundament dafür, was sein soll oder durchgeführt worden ist.
2. Architektur/Design - Übersicht der Software. Schließt Beziehungen zu einer Umgebung und Baugrundsätzen ein, die im Design von Softwarebestandteilen zu verwenden sind.
3. Technisch - Dokumentation von Code, Algorithmen, Schnittstellen und APIs.
4. Endbenutzer - Handbücher für den Endbenutzer, die Systemverwalter und den Unterstützungspersonal.
5. Marketing - Wie man das Produkt und die Analyse der Marktnachfrage auf den Markt bringt.

Voraussetzungsdokumentation

Voraussetzungsdokumentation ist die Beschreibung dessen, was eine besondere Software tut oder tun soll. Es wird während der Entwicklung verwendet, um mitzuteilen, was die Software tut oder tun soll. Es wird auch als eine Abmachung oder als das Fundament für den Konsens darüber verwendet, was die Software tun soll. Voraussetzungen werden erzeugt und von jedem verbraucht, der an der Produktion der Software beteiligt ist: Endbenutzer, Kunden, Produktmanager, planen Betriebsleiter, Verkäufe, Marketing, Softwarearchitekten, Brauchbarkeitsingenieure, Wechselwirkungsentwerfer, Entwickler, und Prüfer, um einige zu nennen. So hat Voraussetzungsdokumentation viele verschiedene Zwecke.

Voraussetzungen kommen in einer Vielfalt von Stilen, Notationen und Formalität. Voraussetzungen können (z.B, verteilte Arbeitsumgebung) in der Nähe vom Design einer Absicht ähnlich sein (z.B, baut kann durch den Rechtsklick auf eine Konfigurationsdatei und ausgesucht die 'bauen' Funktion angefangen werden), und irgendetwas zwischen. Sie können als Behauptungen auf natürlicher Sprache, als angezogene Zahlen, als ausführlich berichtete mathematische Formeln, und als eine Kombination von ihnen allen angegeben werden.

Die Schwankung und Kompliziertheit der Voraussetzungsdokumentation machen es eine bewiesene Herausforderung. Voraussetzungen können implizit und hart sein aufzudecken. Es ist schwierig, genau zu wissen, wie viel und welche Dokumentation erforderlich ist, und wie viel zur Architektur und Designdokumentation verlassen werden kann, und es schwierig ist zu wissen, wie man Voraussetzungen dokumentiert, die die Vielfalt von Leuten denken, die lesen und die Dokumentation verwenden sollen. So ist Voraussetzungsdokumentation häufig unvollständig (oder nicht existierend). Ohne richtige Voraussetzungsdokumentation werden Softwareänderungen schwieriger — und deshalb mehr Fehler anfällig (verminderte Softwarequalität) und zeitraubend (teuer).

Das Bedürfnis nach der Voraussetzungsdokumentation ist normalerweise mit der Kompliziertheit des Produktes, dem Einfluss des Produktes und der Lebenserwartung der Software verbunden. Wenn die Software sehr kompliziert oder durch viele Menschen entwickelt ist (z.B, Mobiltelefonsoftware), können Voraussetzungen helfen besser zu kommunizieren, was man erreicht. Wenn die Software sicherheitskritisch ist und negativen Einfluss auf menschliches Leben haben kann (z.B, Kernkraft-Systeme, medizinische Ausrüstung), ist Dokumentation der mehr Formvorschriften häufig erforderlich. Wenn, wie man erwartet, die Software seit nur einem Monat oder zwei lebt (z.B, sehr kleine Mobiltelefonanwendungen entwickelt spezifisch für eine bestimmte Kampagne), kann sehr wenig Voraussetzungsdokumentation erforderlich sein. Wenn die Software eine erste Ausgabe ist, die später darauf gebaut wird, ist Voraussetzungsdokumentation sehr nützlich, wenn sie die Änderung der Software führt und nachprüft, dass nichts in der Software gebrochen worden ist, wenn es modifiziert wird.

Traditionell werden Voraussetzungen in Voraussetzungsdokumenten angegeben (z.B Textverarbeitungsanwendungen und Spreadsheet-Anwendungen verwendend). Um die vergrößerte Kompliziertheit und sich ändernde Natur der Voraussetzungsdokumentation (und Softwaredokumentation im Allgemeinen) zu führen, werden datenbankzentrische Systeme und Voraussetzungsverwaltungswerkzeuge des speziellen Zwecks verteidigt.

Dokumentation der Architektur/Designs

Architektur-Dokumentation ist eine spezielle Rasse des Designdokumentes. In gewisser Hinsicht sind Architektur-Dokumente die dritte Ableitung aus dem Code (Designdokument, das die zweite Ableitung ist, und codieren Sie Dokumente, die erst sind). Sehr wenig in der Architektur die Dokumente ist zum Code selbst spezifisch. Diese Dokumente beschreiben nicht, wie man eine besondere Routine, oder sogar programmiert, warum diese besondere Routine in der Form besteht, die sie tut, aber stattdessen bloß die allgemeinen Voraussetzungen anlegt, die die Existenz solch einer Routine motivieren würden. Ein gutes Architektur-Dokument ist auf Details kurz, aber auf der Erklärung dick. Es kann Annäherungen für das Design der niedrigeren Ebene andeuten, aber die wirklichen Erforschungshandelsstudien zu anderen Dokumenten verlassen.

Eine andere Rasse des Designs die Doktoren ist das Vergleich-Dokument oder Handelsstudie. Das würde häufig die Form eines Weißbuches annehmen. Es konzentriert sich auf einen spezifischen Aspekt des Systems und deutet abwechselnde Annäherungen an. Es konnte an der Benutzerschnittstelle, dem Code, dem Design oder dem sogar architektonischen Niveau sein. Es wird entwerfen, wie die Situation ist, beschreiben Sie eine oder mehr Alternativen, und zählen Sie das Pro und Kontra von jedem auf. Ein gutes Handelsstudiendokument ist auf der Forschung schwer, drückt seine Idee klar aus (ohne sich schwer auf den stumpfen Jargon zu verlassen, um den Leser zu blenden), und ist am wichtigsten gerecht. Es sollte klar die Kosten beliebiger Lösung ehrlich und erklären, die es als am besten anbietet. Das Ziel einer Handelsstudie ist, die beste Lösung auszudenken, anstatt einen besonderen Gesichtspunkt zu stoßen. Es ist vollkommen annehmbar, keinen Beschluss festzusetzen oder zu beschließen, dass keine der Alternativen genug besser ist als die Grundlinie, eine Änderung zu bevollmächtigen. Ihm sollte als ein wissenschaftlicher Versuch genähert werden, nicht als eine Markttechnik.

</ul>

Wenn

es über Verwandtschaftsdatenbanksysteme spricht, sollte das Dokument folgende Teile einschließen:

</ul></ul></ul>

Es ist sehr wichtig, die ganze Information einzuschließen, die von allen Schauspielern in der Szene verwendet werden soll. Es ist auch sehr wichtig, die Dokumente zu aktualisieren, weil jede Änderung in der Datenbank ebenso vorkommt.

Entwicklerdokumentation

Das ist, was die meisten Programmierer vorhaben, wenn sie die Begriff-Softwaredokumentation verwenden. Wenn er Software schafft, ist Code allein ungenügend. Es muss einen Text zusammen damit geben, um verschiedene Aspekte seiner beabsichtigten Operation zu beschreiben. Es ist für die Codedokumente wichtig, gründlich zu sein, aber nicht so wortreich, dass es schwierig wird, sie aufrechtzuerhalten. Mehrere, Wie - zu und Übersicht-Dokumentation spezifisch zur Softwareanwendung oder dem Softwareprodukt gefunden werden, das von API-Schriftstellern wird dokumentiert. Diese Dokumentation kann von Entwicklern, Prüfern und auch den Endkunden oder Kunden verwendet werden, die diese Softwareanwendung verwenden. Heute sehen wir Los von hohen Endanwendungen im Feld der Macht, der Energie, des Transports, der Netze, des Weltraums, der Sicherheit, der Sicherheit, der Industrieautomation und einer Vielfalt anderer Gebiete. Entwicklerdokumentation ist wichtig innerhalb solcher Organisationen geworden, wie sich das grundlegende und fortgeschrittene Niveau der Information über eine Zeitdauer von der Zeit mit Architektur-Änderungen ändern kann. Folglich hat Entwicklerdokumentation Los wichtig in letzter Zeit besonders im Softwarefeld gewonnen.

Häufig können Werkzeuge wie Doxygen, NDoc, javadoc, EiffelStudio, Sandburg, ROBODoc, SCHOTE, TwinText oder Universaler Bericht verwendet werden, um die Codedokumente zu autoerzeugen - d. h. sie ziehen die Anmerkungen heraus, und Softwareverträge, wo verfügbar, von der Quelle codieren und schaffen Bedienungshandbücher in solchen Formen wie Text oder HTML-Dateien. Codedokumente werden häufig in einen Bezugsführer-Stil organisiert, einem Programmierer erlaubend, eine willkürliche Funktion oder Klasse schnell nachzuschlagen.

Die Idee, Dokumentation zu autoerzeugen, ist für Programmierer aus verschiedenen Gründen attraktiv. Zum Beispiel, weil es aus dem Quellcode selbst herausgezogen wird (zum Beispiel, durch Anmerkungen), kann der Programmierer es schreiben, während er sich auf den Code bezieht, und dieselben Werkzeuge verwenden, die verwendet sind, um den Quellcode zu schaffen, um die Dokumentation zu machen. Das macht es viel leichter, die Dokumentation aktuell zu halten.

Natürlich ist eine Kehrseite, dass nur Programmierer diese Art der Dokumentation editieren können, und es von ihnen abhängt, um die Produktion (zum Beispiel, durch das Laufen eines cron Jobs zu erfrischen, die Dokumente jede Nacht zu aktualisieren). Einige würden das als ein pro aber nicht ein betrügerischer charakterisieren.

Donald Knuth hat auf der Tatsache beharrt, dass Dokumentation ein sehr schwieriger Prozess des nachträglichen Einfalls sein kann und des Lesens und Schreibens kundige Programmierung verteidigt, zur gleichen Zeit und Position als der Quellcode schreibend, und durch automatische Mittel herausgezogen hat.

Aufklärende Programmierung ist das Ergebnis von praktischen Anwendungen der Des Lesens und Schreibens kundigen Programmierung in echten Programmierzusammenhängen.

Das Aufklärende Paradigma schlägt vor, dass Quellcode und Dokumentation getrennt versorgt werden.

Dieses Paradigma wurde durch dieselben experimentellen Ergebnisse begeistert, die Kelp erzeugt haben.

Häufig müssen Softwareentwickler im Stande sein, Information zu schaffen und auf sie zuzugreifen, die nicht dabei ist, ein Teil der Quelldatei selbst zu sein. Solche Anmerkungen sind gewöhnlich ein Teil von mehreren Softwareentwicklungstätigkeiten, wie Codespaziergänge und Halten nach Backbord, wo Drittquellcode auf eine funktionelle Weise analysiert wird. Anmerkungen können deshalb dem Entwickler während jeder Bühne der Softwareentwicklung helfen, wo ein formelles Dokumentationssystem Fortschritt hindern würde.

Kelp versorgt Anmerkungen in getrennten Dateien, die Information mit dem Quellcode dynamisch verbindend.

Benutzerdokumentation

Verschieden von Codedokumenten sind Benutzerdokumente gewöhnlich in Bezug auf den Quellcode des Programms viel verschiedener, und beschreiben stattdessen einfach, wie es verwendet wird.

Im Fall von einer Softwarebibliothek konnte es effektiv gleichwertig sein und lohnen sich, die Codedokumente und Benutzerdokumente zu vereinigen, aber für eine allgemeine Anwendung ist das nicht häufig wahr.

Gewöhnlich beschreibt die Benutzerdokumentation jede Eigenschaft des Programms, und hilft dem Benutzer beim Verständnis dieser Eigenschaften. Ein gutes Benutzerdokument kann auch gehen, so weit man gründliche Fehlerbeseitigungshilfe gibt. Es ist für Benutzerdokumente sehr wichtig, und für sie nicht verwirrend zu sein, um aktuell zu sein. Benutzerdokumente brauchen auf keine besondere Weise organisiert zu werden, aber es ist für sie sehr wichtig, durch den Index zu haben. Konsistenz und Einfachheit sind auch sehr wertvoll. Wie man betrachtet, setzt Benutzerdokumentation einen Vertrag ein, der angibt, was die Software tun wird. API-Schriftsteller werden sehr gut zum Schreiben guter Benutzerdokumente vollbracht, weil sie sich der Softwarearchitektur und verwendeten Programmiertechniken wohlbewusst sein würden. Siehe auch das Technische Schreiben.

Es gibt drei breite Wege, auf die Benutzerdokumentation organisiert werden kann.

1. Tutorenkurs: Eine Tutorannäherung wird als das nützlichste für einen neuen Benutzer betrachtet, in dem sie durch jeden Schritt geführt werden, besondere Aufgaben zu vollbringen.
2. Thematisch: Eine thematische Annäherung, wo sich Kapitel oder Abteilungen auf ein besonderes Gebiet von Interesse konzentrieren, ist von allgemeinerem Nutzen einem Zwischenbenutzer. Einige Autoren ziehen es vor, ihre Ideen durch den gestützten Artikel ein Kenntnisse zur Erleichterung der Benutzerbedürfnisse zu befördern. Diese Annäherung wird gewöhnlich durch eine dynamische Industrie wie Informationstechnologie geübt, wo die Benutzerbevölkerung mit der Fehlerbeseitigung größtenteils aufeinander bezogen wird, fordert
3. Liste oder Verweisung: Der Endtyp des Ordnungsprinzipes ist derjenige, in dem Befehle oder Aufgaben einfach alphabetisch verzeichnet oder logisch häufig über Quer-verweise angebrachte Indizes gruppiert werden. Diese letzte Annäherung ist von größerem Nutzen fortgeschrittenen Benutzern, die genau wissen, nach welcher Information sie suchen.

Eine häufige Beschwerde unter Benutzern bezüglich der Softwaredokumentation ist, dass nur eine dieser drei Annäherungen in den nahen Ausschluss der anderen zwei gebracht wurden. Es ist üblich, zur Verfügung gestellte Softwaredokumentation für Personalcomputer zur Direkthilfe zu beschränken, die nur Bezugsinformation über Befehle oder Menüpunkte geben. Der Job, neue Benutzer zu unterrichten oder erfahreneren Benutzern zu helfen, meist aus einem Programm zu werden, wird privaten Herausgebern verlassen, denen häufig bedeutende Hilfe vom Softwareentwickler gegeben wird.

Marktdokumentation

Für viele Anwendungen ist es notwendig, einige Beförderungsmaterialien zu haben, um zufällige Beobachter dazu zu ermuntern, mehr Zeit zu verbringen, über das Produkt erfahrend. Diese Form der Dokumentation hat drei purposes: -

1. Den potenziellen Benutzer über das Produkt aufzuregen und in ihnen einen Wunsch danach einzuträufeln, beteiligter damit zu werden.
2. Sie darüber zu informieren, was genau das Produkt tut, so dass ihre Erwartungen damit übereinstimmen, was sie erhalten werden.
3. Die Position dieses Produktes in Bezug auf andere Alternativen zu erklären.

Eine gute Markttechnik soll klare und denkwürdige Mottos zur Verfügung stellen, die den Punkt veranschaulichen, den wir befördern, und auch die Zwischenfunktionsfähigkeit des Programms mit irgend etwas anderem zur Verfügung Gestelltem durch den Hersteller betonen möchten.

Zeichen

Siehe auch

• API-Schriftsteller
• Vergleich von Dokumentationsgeneratoren
• Design durch den Vertrag
• Docstring
• Dokumentation
• Benutzerhilfe
• Designdokument

• README Dateien
• Vereinigte modellierende Sprache UML
• Des Lesens und Schreibens kundige Programmierung

Außenverbindungen

• Kelp - ein Quellcodeanmerkungsfachwerk für den architektonischen, das Design und die Entwicklerdokumentation.
• automatisierte Softwaredokumentation - Anwendungsdokumentation
• ISO Dokumentationsstandardkomitee - Internationale Organisation für das Standardisierungskomitee, das Benutzerdokumentationsstandards entwickelt.