Was gehört alles in eine richtige Dokumentation?

[Back2Code]

Hallo alle zusammen, mich würde es interessieren von euch langjährigen Entwicklern mal zu erfahren was denn alles so in eine ordentliche Dokumentation rein gehören sollte. Habe bisher noch keine erstellt und würde mich über Beispiele & Leitfäden freuen.

[Lemmy]

Tach,

präzisier bitte mal:
was für ne Dokumentation (komplette Software, Entwicklerlibs,..)? Für wen soll die sein (Anwender, Entwicklerkollegen, Nachfolger,...)?

[Back2Code]

Zitat von Lemmy:

Tach,

präzisier bitte mal:
was für ne Dokumentation (komplette Software, Entwicklerlibs,..)? Für wen soll die sein (Anwender, Entwicklerkollegen, Nachfolger,...)?

Komplette Software, soll für andere Entwicklerkollegen / Projektmanager sein.

[MaBuSE]

Zitat von Back2Code:

Komplette Software, soll für andere Entwicklerkollegen / Projektmanager sein.

Wie haben hier im Haus 4 Arten von Dokumentationen für jedes Projekt.

1. Benutzerhandbuch für Endanwender
   Viel Prosa und Grafiken, damit sich auch neue Anwender schnell zurechtfinden.
   Es werden die typischen Arbeitsabläufe beschrieben und in einem Referenzkapitel alle Funktionen / Formulare.
2. Systemdokumentation für Entwickler / Support
   Zur Systemdokumentation gehören auch die Dokumente vor der Programmierung (z.B. Pflichtenheft, Anforderungen, Änderungsanforderungen, ...)
   Ein Teil der System-Dokumentation ist ein PDF das aus den Kommentaren des Quelltextes generiert wird (mit Doc-o-matic). Das ist vor allem wichtig, wenn bestimmte Units auch von anderen Programmen benutzt werden.
   Auch zählen Klassendiagramme, Ablaufdiagramme, Unit-Abhänigkeiten usw. dazu.
   Die System Dokumentation sind bei uns mehrere Dokumente.
   Es macht keinen Sinn das alles in ein PDF zu zwängen.
3. Changehistory
   Jede Änderung wird in Releasenotes festgehalten. Die Releasenotes sind in Prosa und für den Endanwender geschrieben. Jedes Mal, wenn eine neue Version in Produktion gegeben wird, wird die Releasenote um die Änderungen zu Vorversion ergänzt.
   Für die Entwickler gibt es eine eigene Historie. Diese besteht aus den Commit Kommentaren unserer Versionsverwaltung (ClearCase bzw. git).
4. Sonstige
   Es gibt immer mal Dokumente, die in keine der oberen Kategorien passen, die wandern in den misc Ordner

Ich hoffe das hilft Dir.
MaBuSE

[Nintendo]

Hallo,

- Schritt für Schritt Anleitung der Bedienung der Software

- Bei Softwareentwicklungssystemen genügend Beispiele, die möglichst alle Faähigkeiten des Entwicklungssystems abdecken. Plus eine ausführliche Hilfe für alle Prozeduren, Funktioen, Klassen, Methoden,...

- Verständliche Anleitung zur Benutzung von Zusatztools.

- Das heißt aber bei Kommandozeilenprogrammen dann auch:
jede Option in ihrer Bedeutung genau erklären
Genaue Angabe, in welcher Reihenfolge die Optionen angegeben
werden müssen oder besser noch das Tool so programmieren, das die
Reihenfolge der Optionen egal ist.

- Für diesen Fall auch Beispiele für die Verwendung des
Kommandozeilenprogrammes.

Bei Gui Programm:
- sinnvolle Voreistellungen
- wiederum Erklärung aller auswählbaren Optionen mit deren Bedeutung
- Auch hier Beispiele mit verschiedenen Einstellungen.

Ich hoffe, das hilft erst mal. Inzwischen ist mir jemand zuvor gekommen. Der hat schon alles Wichtige zusammengefasst.

[Back2Code]

Gibt es freie Software die gut zum erstellen von Programmabhängigkeiten geeignet ist?

[MaBuSE]

Zitat von Back2Code:

Gibt es freie Software die gut zum erstellen von Programmabhängigkeiten geeignet ist?

Schau mal den Link in meinem Posting oben
(bzw. Im Zitat unten)

Zitat von MaBuSE:

1. Systemdokumentation für Entwickler / Support
   ..., Unit-Abhänigkeiten ...

Ich hoffe das hilft Dir.
MaBuSE

[Back2Code]

Zitat von MaBuSE:

Zitat von Back2Code:

Gibt es freie Software die gut zum erstellen von Programmabhängigkeiten geeignet ist?

Schau mal den Link in meinem Posting oben
(bzw. Im Zitat unten)

Zitat von MaBuSE:

1. Systemdokumentation für Entwickler / Support
   ..., Unit-Abhänigkeiten ...

Ich hoffe das hilft Dir.
MaBuSE

Ah sorry, hab den Link total übersehen. Sieht auf jedenfall schon mal sehr interessant aus. Wie würdet ihr mir empfehlen, wie man sich am besten in fremde Klassen einzuarbeiten hat die man nicht geschrieben hat und der Programmierer davon auch nicht mehr vorhanden ist...

[MaBuSE]

Zitat von Back2Code:

Sieht auf jedenfall schon mal sehr interessant aus.

Danke

Das Tool kannst Du Dir auch ansehen:
http://www.delphipraxis.net/internal...ct.php?t=87932

Zitat von Back2Code:

Wie würdet ihr mir empfehlen, wie man sich am besten in fremde Klassen einzuarbeiten hat die man nicht geschrieben hat und der Programmierer davon auch nicht mehr vorhanden ist...

Doc-O-matic ist ein Programm, dass den Quellcode scannt und daraus eine Dokumentation baut.
(Es gibt auch eine kostenlose Version)
Es wird auch die Struktur der Objekte sichtbar.
Richtig sinnvoll ist es allerdings erst, wenn der Programmierer auch Kommentare in den Quellcode geschrieben hat. Diese werden von Docomatic verwendet.
-> Die Delphi Hilfe ist auch mit Doc-O-Matic erstellt worden. (Zumindest die von D2007, bei den aktuellen Versionen weiss ich es nicht).

ESS Model
sieht ein wenig aus die Modelansicht von Delphi.
http://essmodel.sourceforge.net/

Dependency Walker
Um die Abhänigkeiten der Exe anzusehen:
(also welche *.dll Dateien werden benötigt)
http://www.dependencywalker.com/

[BUG]

Zitat von Back2Code:

Wie würdet ihr mir empfehlen, wie man sich am besten in fremde Klassen einzuarbeiten hat die man nicht geschrieben hat und der Programmierer davon auch nicht mehr vorhanden ist...

Mal unabhängig von der Dokumentation: Den Pfad eines typischen Ablaufes nachvollziehen.
Dabei können auch Klassen-, Objekt- und Sequenzdiagramme entstehen, die man dann der Dokumentation hinzufügen kann. Außerdem man kann dabei auch den Quelltext kommentieren, um später daraus Dokumentation zu generieren. Allerdings sollte man dann vielleicht im Kommentar anmerken, wenn es keine gesicherte Erkenntnis darstellt.