Was gehört alles in eine richtige Dokumentation?

[r2c2]

Die Antwort auf alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".

Zu Dokumentation hat fast jeder eine Meinung. Und je nachdem, wen man fragt wird man *sehr* unterschiedliche Antworten erhalten. Fakt ist: Eine pauschale Antwort gibt es nicht.

Demnach musst du die Frage für dich beantworten. Dabei solltest du folgendes bedenken:
- Wer soll die Doku lesen? Und was erwarten diese? Doku ist mit Sicherheit falsch, wenn sie an den Anforderungen der Stakeholder vorbei geht. Und das kann je nach Projekt sehr unterschiedlich sein.
- Doku ist kein Selbstzweck. Je mehr du davon hast, desto aufwendiger ist es, sie zu pflegen. Und veraltete Doku ist i.d.R. schlechter als gar keine.
- Je näher die Doku am Code ist (rein räumlich gesehen), desto wahrscheinlicher ist, dass sie gepflegt wird. Selbsterklärender Code > Kommentare im Code > Doku mitversioniert im selben Repository > Doku außerhalb des Repos > Doku auf Paper.
- Doku, die keine neue Info hat, ist kontraproduktiv. Doku zu dem Konstruktor, die sagt "Create erzeugt ein neues Objekt" oder noch besser "Konstruktor der Klasse" ist sinnloses Gebabbel und sollte man unterlassen.
- Je mehr Stakeholder du hast, desto mehr Doku ist nötig. Schreibst du ne API für hunderte anderer Entwickler, brauchst du mehr Doku, als wenn du der einzige bist, der das unter die Finger kriegt. Wenn sich das Entwicklerteam ständig ändert, brauchst du mehr Doku, als wenn du ein festes, unveränderliches Team hast.
- Je mehr sich der Code ändert, desto schneller veraltet Doku und desto weniger solltest du haben. Abstrakte Basisklassen musst du eher beschreiben als temporäre Implementierungen, die beim nächsten Refactoring eh wieder wegfallen. Ebenso ist es sinnvoller, die grobe Architektur zu dokumentieren (weil die sich nur langsam ändert), als irgendwelche privaten Methoden, die eh ständig umgeschrieben werden. Dokumentiere Abstraktes und Allgemeines eher als konkretes.
- Doku macht nur Sinn, wenn sie auch gelesen wird. Wenn sie zu detalliert ist und niemand den Detailgrad braucht, ist das vergeudete Zeit. Diagramme sind gut. Denn damit kann man Zusammenhänge übersichtlich zeigen, die man im Code nie sehen würde, weil man im Code quasi immer mit der Lupe vor nem monumentalen Wandteppich steht. Diagramme, die aber nicht übersichtlich sind, sind wertlos.
- Wenn du wissen willst, was gute Doku ist, guck dir schlechte an.
- Besser noch: frag die Stakeholder, die die Doku lesen sollen nach Beispielen für gute und schlechte Doku. Frag sie, was sioe ganz konkret brauchen und erwarten. Frag sie, was sie haben wollen und wie sie die Doku benutzen würden. Ganz konkret die Personen, die das betrifft. Wir hier können nur Anhaltspunkte liefern und ggf. aus dem Nähkästchen plaudern. Aber wir können hier keine Abschließende Antwort liefern, weil wir dein Projekt nicht kennen.
- ...

mfg

Christian

[Bernhard Geyer]

Zitat von r2c2:

Die Antwort auf alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".
...
...
...

Besser hätte man es nicht schreiben können

[delfox]

Hi!

Oft schon die Basics - Zugangsdaten und bei externen die Ansprechpartner. Welche Versionen kamen zum Kunden. Welche Versionen sind wo archiviert. Dann der Quellcode. Wenn eine Datenbank genutzt wird, dann ein ER Diagramm. Welcher Aufwand wurde betrieben, damit man bei weiteren Projekten schauen kann, ob man im Budget war.

[Klaus01]

Laut Uncle Bob ist eine Software ausreichend dokumentiert
wenn zu allen Methoden/Funktionen Testfälle/Unit-Tests vorliegen.

Grüße
Klaus

[blondervolker]

Such einfach bei den "GROßEN"...
Die haben verschiedene Textepassagen meistens... per "RA" überprüfen lassen...

[DeddyH]

In der Doku?

[blondervolker]

Oiiihhh,habe gepennt.
Naja mein Spruch unten drunter gilt leider auch für mich....

[Back2Code]

Gibt es hier im Forum noch Beispiele in Form von Pdf einer richtigen Software Dokumentation wo auf Funktionen / Parameter von Klassen / Methoden eingegangen wird?

[Graberius]

Sichwort Dokumentation
Egal ob du jetzt Object Pascal, C/C++, Java, Groovy, Velocity, HTML oder JavaScript Programmierst...
Kommentier wenigstens was eine Methode oder Funktion machen soll!!!

[MaBuSE]

Zitat von Back2Code:

Gibt es hier im Forum noch Beispiele in Form von Pdf einer richtigen Software Dokumentation wo auf Funktionen / Parameter von Klassen / Methoden eingegangen wird?

Ja,

z.B.http://docs.embarcadero.com/products...hivclwin32.pdf
( Achtung: das PDF hat 25622 Seiten und ist ca. 400 MB Groß )

Das ist die Hilfe zur VCL von D2007 als PDF.
Diese wurde die die Online-Hilfe mit Doc-O-Matic erstellt.
(Habe ich schon weiter oben beschrieben)

Apropos Delphi Dokumentation / Hilfe:
Das hier ist eine ganz gute Übersicht
http://docs.embarcadero.com/products...udio/index.php