Was ist bei einer Programmdokumentationen zu berücksichtigen?
Hey Community!
ich hätte eine Bitte bzw. eine Frage an euch:
Könnt ihr hier alle ein Paar Fakten zusammentragen, die bei einer Programmdokumentation zu berücksichtigen sind?
Was ich meine:
Was genau sollte man dokumentieren und was macht Sinn?
Da vorort ein Wirrwar von verschiedenen unstandardisierten Programmdoku's herscht, bin ich auf der Suche nach einem gewissen Standard, der alles beinhaltet was man wissen sollte.
Würde mich freuen wenn ein Paar Vorschläge und/oder Fakten gepostet werden.
Vielen Dank!
Gruß
ETM
We roll tonight,
on the guitar BYTE!
Hier wäre noch relevant, ob du dich auf eine Dokumentation für den Anwender oder für potentielle Entwickler beziehst.
Bei einer Dokumentation für den Anwender würde ich zu aller erst auf den Einsatzzweck des Programms / Softwaresystems eingehen.
Anschließend würde ich näher ins Detail gehen und die Anwendung / Anwendungen die zum System gehören Beschreiben.
Dazu zählen:
- welchen Einsatzzweck hat die Anwendung
- wie ist die Funktionsweise der Anwendung
- mit welchen weiteren Komponenten kommuniziert die Anwendung (relevant bei Verwendung von Webservices o.ä.)
Der nächste Schritt wäre die Anwendung detaillierter zu Beschreiben. Handelt es sich um eine Anwendung mit GUI wäre es angebracht auf die Oberflächen einzugehen. Welche Möglichkeiten hat der Anwender auf der jeweiligen Oberfläche?
Auch Informationen zur Konfiguration der Anwendung sollten hier beschrieben werden. Das ganze eben für jede Anwendung die zum System gehört.
Kommunizieren die Anwendungen mit einer Datenbank würde ich in einem eigenen Abschnitt auch auf die Datenbankobjekte eingehen.
Das wäre zumindest was ich in einer Dokumentation für relevant halte.
Wissen ist nicht alles. Man muss es auch anwenden können.
PS Fritz!Box API - TR-064 Schnittstelle | PS EventLogManager |
Erstmal vielen Dank für die schnelle Antwort!
Zum Zweiten muss ich mich entschuldigen: die Doku soll für die internen Entwickler hergenommen werden, um sich bspw. später einmal in alte Programme/Programmstände eindenken zu können.
Danke.
We roll tonight,
on the guitar BYTE!
Für die Internen Entwickler reichen meistens gute Kommentar
in einer richtigen internen doku beschreibe ich meistens das gesamtkonzept der software, die einzelnen klassen werden grob angeschnitten und bei besonderheiten wird direkt darauf hingewiesen
das gepaart mit unittest und kommentaren sehe ich als mehr als ausreichend an
MfG Paul
In komplizierteren Kommunikations-Szenarios macht man am besten eine einfache Zeichnung/Diagramm und erläutert diese.
Generell habe ich festgestellt das eine legere geschriebene Doku besser verstanden wird, als eine die hochoffiziell in beinahem Beamtendeutsch formuliert. So beschränkt man sich auch auf das relevante und man muss sich nicht durch hunderte Seiten unwichtigen Kleinkram wühlen, bis man einen Überblick hat.
Hallo EnterTheMax,
ein wichtiger Punkt ist die Aktualität der Dokumentation - ob nun für die Software-Entwickler oder für jemand anderes - die Dokumentation wird nicht nur einmal erstellt und bleibt dann bis ans Ende aller Tage unverändert, sondern es ist wichtig die Dokumentation an Änderungen und Erweiterungen anzupassen. Den Aufwand für die Dokumentationspflege sollte man auch beim initialen Erstellen von Dokumentation nie außer acht lassen.
-yellow
Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).
Mein Blog: Yellow's Blog auf sqlgut.de
Hallo EnterTheMatrix,
würde mich wundern, wenn wir das Thema nicht schon mehrfach besprochen hätten. Benutze mal die Forensuche und poste die besten Treffer hier.
Daher hier nur in aller Kürze: Für eine Klassenbibliothek ist die Doku per XML-Kommentaren direkt im Code am sinnvollsten. Daraus entsteht eine Referenzdokumention der Klassen wie man sie aus der MSDN kennt. Für Anwendungssysteme als Ganzes ist eine Architekturdoku am wichtigsten, am besten in Diagrammform zusammen mit einer verbalen Erläuterung der wichtigsten Designentscheidungen. Nicht zu umfangreich, damit der Pflegeaufwand vertretbar bleibt.
herbivore
Hallo,
Aktualisieren eines Systems mithilfe von Visualisierungs- und Modellierungstools zeigt exemplarisch wie Diagramme für das Verständnis eins SW-Systems verwendet werden können. Auch wenn es für VS Ultimate ist kann die Idee dahinter mit freien Tools umgesetzt werden.
Für einzelne Klasse sind zusätzlich zur XML-Doku auch Tests eine wunderbare Dokumention und zeigen zugleich die Anwendung der Klasse bzw. zeigen ihr Verhalten (zB wann kommt es zu Fehlern). Dies ist aber eher firmenintern geeigent, außer die Tests sollen/können veröffentlicht werden.
mfG Gü
Stellt fachliche Fragen bitte im Forum, damit von den Antworten alle profitieren. Daher beantworte ich solche Fragen nicht per PM.
"Alle sagten, das geht nicht! Dann kam einer, der wusste das nicht - und hat's gemacht!"