Ohne jetzt eine Grundsatzdiskussion starten zu wollen, aber vernünftige Dokumentation ist imho eine komplexe, anwendungs-, organisations- und zielgruppenspezifische Aufgabe.
Es ist ein Kommunikationsmedium und somit inherent komplex und inherent unscharf (weil Menschen sich eben missverstehen).
Für Systemdokumentation ist das folgende hilfreich:
In jedem Agenten, jeder Funktion und jede Subroutine im Kopf sowas zu schreiben wie:
%rem
wann erstellt:
von wem erstellt::
von wem geändert (Liste):
Kurzbeschreibung:
Langbeschreibung:
ReM ausgeremt: Beteiligte Gestaltungselemente war Schwachsinn und das mache ich auch nicht.
%end rem
Das ist aber nicht die gesamte Dokumentation.
Daneben gibt es noch grobgranularere Überblicksdokumentationen, wo die Beziehungen zwischen den Code Elementen beschrieben werden (z.B. Beziehung von Agent zu Dokument-Typ). Graphische Methoden bieten sich hier an. Für Notes benutze ich dabei eine freizügige Benutzung von allen Software-Diagrammtypen, die mir in Visio gut gefallen. Das ganze fundiert mit gewissen UML-Kenntnissen und v.a. auch viel Freitext.
Auch in Java ist die Frage, ob man jetzt UML mehr als Skizzenformat oder als semantisch eindeutige Modellierungsformat benutzen soll, umstritten.
Automatisierende Tools sind sowieso grundsätzlich umstritten. Viele Leute befürworten die Anschaffung von Digitalen Kameras und möglichst großen Whiteboards.
Bei einem guten Softwareprozess gibt es im Projektverlauf einen Fluss, wo die Enddokumentation quasi aus den Planungsdokumenten zu Anfang abgeleitet sind und das funktioniert.
Ich hab schon einige Organisationen erlebt, die durch die teure Erstellung von "Dokumentationsrichtlinien" das ganze bürokratischer, verlogener und ineffizienter gemacht haben als es vorher war.
Ansonsten würde ich mir Teamstudio anschaffen und nur das zu dokumentieren, was nicht durch Teamstudio Analyzer abgedeckt ist.
Gruß Axel