Eure favorisierte Form der Dokumentation

[Phoenix]

Wikis haben Erfahrungsgemäß das Problem, dass sie schnell veralten. Kaum jemand denkt im Regelfall daran, wenn er etwas im Code ändert, das auch im Wiki nachzupflegen. Wir haben bei mir auf der Arbeit das gleiche Problem. Das lässt sich mit etwas Konsequenz und Checklisten (Punkt: Doku aktualisiert? Beim Ticket / Task der abzuarbeiten ist) zwar etwas eindämmen, aber nicht ganz vermeiden.

Ich persönlich bin ein Fan von guter Code-Dokumentation, bei der man auch konzeptionelle Doku zu Architektur und abläufen in der Solution als Einzelfiles mit eincheckt und dort mit pflegt. Die aktualisierte Doku ist damit nur einen weiteren Commit entfernt, und man hat alles beisammen. Aus der Doku (Kommentare im Code sowie Konzeptionelle Doku) wird beim Release dann auch gleich die technische Doku als Webseite mit gebaut, über die der gesamte Inhalt inkl. Architekturdiagrammen etc. abrufbar ist. Wir benutzen dafür DocumentX von Innovasys. Wir sind aber ja auch eine .NET Schmiede, und ich weiss nicht ob das auch mit Delphi tut.

Grundsätzlich halte ich den Ansatz, die Doku zusammen mit dem Quellcode zusammen zu versionieren, und alles in einem Checkout zu haben, aber für das beste. Bei mir vor allem deswegen, weil wir das Dokumentationstool eben auch gleich als Plug-in in der IDE haben, und wir bei der Dokumentation daher niemals einen Medienbruch haben. Dieses Unkompliziertheit, alles gleich bei der Hand zu haben, sorgt dafür das die Doku auch deutlichst besser gepflegt wird als in einer separaten Ablage (wie z.B. ein Wiki).