Eure favorisierte Form der Dokumentation

[Daniel]

Tach auch,



manch einer von Euch klickt ja nicht nur in der DP herum, sondern programmiert ja nebenbei auch noch. Unter Umständen sogar mit Kollegen.
Mich würde mal interessieren, was sich da bei Euch als effizienteste Form der Dokumentation herauskristallisiert hat. Sei es Dokumentation, die fokussiert ganz konkret einzelne Aspekte Eurer Projekte adressiert oder auch Dokumentation, die das "Große Ganze" beschreibt und die Zusammenhänge zwischen den diversen Bestandteilen bzw. Modulen.

Ich kenne Firmen, die erfolgreich mit Word und Excel arbeiten, andere legen sich ein Wiki an. Manche Dokumentationsprojekte funktionieren, andere driften vom Projekt ab und schaffen so eine vielleicht lustige, aber nutzlose Parallelwelt.
Was hat bei Euch gut funktioniert?


Vorrangig bin ich an Praxisberichten interessiert - weniger an Euren Vorstellungen, warum Methode X oder Y Eurer Ansicht nach nicht funktionieren kann.

[dummzeuch]

Ich habe Wikis bei zwei Jobs ausprobiert, aber ich bin anscheinend der einzige, der sie praktisch findet und/oder in der Lage ist, darin Artikel zu schreiben. Funktioniert hat eigentlich immer nur Word (oder OpenOffice), reine Textdateien und Uebersichtsbilder (mit yEd).

Eine etwas abwegige Art der Dokumentation sind fuer mich meine Blog-Posts. Solange keine Firmeninterna davon betroffen sind, finde ich es ganz gut, wenn ich mir selbst auf diese Art eine Gedaechtnisstuetze gebe und nebenbei vielleicht auch anderen helfe. Z.B. diese hier:

http://blog.dummzeuch.de/2015/04/27/...-tar-archives/

http://blog.dummzeuch.de/2015/04/09/...ndows-service/

[Lemmy]

wir verwenden gerade auch ein Wiki, wobei ich dummzeuchs bestätigen kann: Es gibt nur sehr wenige die Input liefern, noch weniger die sich im Wiki informieren. Wenn aber inzwischen Fragen bei mir landen kann ich die oft über einen entsprechenden Link ins Wiki einfach beantworten - deshalb werde ich auf dem Weg erst mal weiter machen.

Office Dateien bin ich ganz schnell wieder weg gekommen, da in kürzester Zeit unterschiedliche Versionen im Umlauf waren...

[vagtler]

Wir verwenden sowohl für unsere internen Produkte als auch für alle externen Projekte ein Enterprise-Wiki mit integrierten Google Docs zur Dokumentation. Das hat sich für uns als effizienteste Art der Kollaboration erwiesen.

[Bernhard Geyer]

Ich denke es kommt immer auf die Art der Dokumentation an.

Benutzerhandbücher, Pflichtenheft, ...: Word-Dokument das als PDF zum Kunden gesendet wird.
Interne Dokumentation die auch mal "Formlos" erfolgt: Wiki. Dazu haben wir mittlerweile Confluence (https://www.atlassian.com/software/confluence)
Dan natürlich für Problemfälle/Fehler/Anforderungen/User Strories/ gibts Jira.

Punkt 2 und 3 lassen sich schön miteinander Verknüpfen und können auch direkt mit dem Kunden zusammen mit "Leben" gefüllt werden.
Gegenüber früher werden weniger Excellisten/Word-Dokumente oder Mails ausgetauscht.

[BUG]

Ich sehe gerade den Ablauf in einem akademischen Projekt, wobei mir die internen Releases mit dazugehörigen Architekturdokumenten gefallen. So ein Dokument zwingt einen im Großen ab und zu ein konsistentes Bild zusammenzutragen und lesbar auszuformulieren. Ist natürlich aufwendig.

[TBx]

Für die Nachvollziehbarkeit es Codes gilt: The code is the documentation. Verstehe ich den nach einiger Zeit nicht mehr, habe ich falsche Bezeichner gewählt und korrigiere das.
Für die Hintergründe des Projektes oder auch Erķlärungen, warum welcher Weg eingeschlagen wurde, gibt es reine Textdateien, PDFs, jpgs --> auf jeden Fall nur Formate, für die es eine Vielfalt von Readern gibt.
Das fliegt dann in ein Dokumentationsverzeichnis, welches mit allem anderen im GIT landet. Für die Historie ist das GIT da, lange Unit.- oder Funktionsheader, in denen jeder Sch*** dokumentiert ist, sind mir ein Greul.
Ich scheue auch nicht davor zurück, in Kommentaren nur auf Dokumente im Dokumentationsverzeichnis zu verweisen.

[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).

[Dejan Vu]

Wir dokumentieren mit Confluence. Dabei werden Architekturansätze, Codepatterns und sonstige Systemdokumentation festgehalten und gepflegt. Code ist clean, d.h. enthält die notwendigen Dokumentationen der API und wird durch Review so gehalten, das er verständlich ist.

Über Resharper sehen wir, wann sich (zumindest bei den Parametern) die ///-Doku zu sehr von der Methode unterscheidet.

Klappt. Weil wir einen Softwarearchitekten haben, dessen Hobbies u.a. Peitschen, Teeren und Federn ist.

[Luckie]

Das funktioniert nicht. Also eine externe Dokumentation. Da könne mir die Theoretiker noch so viel erzählen. Wer sucht im Wiki schon nach Antworten, wenn er den Quellcode vor sich im Editor offen hat? Und eine externe Doku hängt dem aktuellen Stand immer hinterher. Und ich habe noch keinen Kollegen getroffen, der die externe Doku pflegt. Besser aussagekräftiger Code mit sparsamen Kommentaren warum so und nicht anders.