Professionelle Software-Dokumentation

[Balu der Bär]

Moin alle miteinander,

ich interessiere mich zur Zeit für Software-Dokumentationen, bzw. wie man diese korrekt und ausführlich erstellt (für Kunden, Lehrer, Ausbilder oder einen selbst). Mein Problem ist nur, dass ich mich noch nie mit so etwas beschäftigt habe.

Was genau gehört also alles in so einen Dokumentation herein? Programmaufbau, verwendete Bibliotheken, Funktionserklärungen und dies alles? Gibt es spezielle Formate oder Vorgaben an die man sich halten kann / muss?

Bei meiner Internetrecherche bin ich nicht wirklich fündig geworden und das Buch, dass mir empfohlen wurde ist mit 40 € so kurz vor Weihnachten für mich auch nicht drin.


Ich würde mich freuen wenn mir jemand ein paar Quellen bzw Informationen liefern könnte, vielen Dank schonmal.

[Phoenix]

Zitat von Balu der Bär:

Was genau gehört also alles in so einen Dokumentation herein?

Das hängt Prinzipiell erstmal davon ab, für Was Du eigentlich dokumentierst.

Erstellst Du z.B. eine Programm-Bibliothek, dann sollten alle exportierten Funktionen mit sämtlichen Parametern dokumentiert werden. Eine Doku-Erzeugung aus dem Quellcode heraus (XML-Doc) bietet sich für sowas natürlich ideal an.

Brauchst Du eine Doku für Anwender interessieren die einzelnen Methoden niemanden. Die wollen/brauchen die Screenshots aller Formulare, einen Überblick über die Menüstruktur, eine Art 'HowTo': Wenn ich DAS machen will, welches Menü muss ich aufrufen, und wo muss ich was eingeben?

Brauchst Du eine Doku für Dich / Dein Entwicklunsgteam brauchst Du weder 1. (die im Team können bei sowas zur Not im Source nachgucken), und 2. auch nicht. Da brauchst Du einen gesamtüberblick - also gutes ERD für die Datenbank mit allen Relationen etc., UML-Diagramme über die verwendeten gemeinsamen Klassen, Ablaufdiagramme wo nötig, Use-Cases sind hier manchmal sehr informativ.

Wie Du siehst hängt das also von mehreren Sachen ab. So eine pauschale Antwort kann Dir deswegen niemand geben.

[Balu der Bär]

Moin Sebastian,

stimmt daran hatte ich gar nicht gedacht.

Nehmen wir also einmal an ich hätte ein Programm (z.B. einen kleinen Texteditor) als Freelancer für eine Firma programmiert und verkaufe diesen nun mitsamt Quelltext an die Firma. Diese möchte nun das ich eine komplette Dokumentation mitliefere. Spontan fallen mir da folgende Punkte ein:

• ausführliche Beschreibung wie das Programm zu bedienen ist bzw was es überhaupt macht
• UML-Diagramme (kennt jemand eine gute Software dafür, am besten Freeware) & Programmablaufdiagramme
• verwendete Schnittstellen / Bibliotheken / Fremdkomponenten
• Funktionsbeschreibungen und -erklärungen

Sonst noch etwas beim Beispiel Texteditor? Und wie sieht es eigentlich mit kurzen Quelltextkommentaren aus?

[mkinzler]

Zitat:

UML-Diagramme (kennt jemand eine gute Software dafür, am besten Freeware)

http://www.jeckle.de/umltools.htm
-D2006 ( )

[Luckie]

Wenn du die UML Diagramme mitlieferst, dann erübrigt sich eigentliche ine ausführliche Beschreibung des Quellcodes. Oder wie Hagen immer sagt: "Es gibt keine bessere Dokumentation, wie den quellcode selber." Eventuell noch Prozedurköpfe mit einer kurzen Beschreibung und an den stellen, wo nicht klar ersichtlich wird, warum du etwas so gelöst hast noch einen Kommentar. ein Programmierer sollte dann damit klarkommen.

[Balu der Bär]

Okay danke euch, habe mir mal die ModelMaker Demo heruntergeladen und werde mal gucken was das Ding so kann.

[Darkchild]

Nabend,

es kommt darauf an wie Du das ganze aufbaust.
Der Umfang einer Software Dokumentation ist genormt und enthält unteranderem die Struktogramme der Einzelnen Funktionen, eine Variablen Liste, funktionsliste mit Beschreibung, verwendete Testumgebung uvm.

Oder Du erstellst eine Doku in Form eines Benutzerhandbuches.

Aber bei näherem Interesse kann ich Dir auch mal alles schicken was gebraucht wird, oder eine Beispieldokumentation für ein kleines Projekt welches ich erstellt habe, diese Doku richtet sich dann auch an die gängige Norm.

Gruss
Darkchild