[php] Dokumentation von/in Software-Projekten

[Andre Temme]

Hallo zusammen,

immer wieder merke ich, dass Dokumentation mehr etwas ist, über das man 
spricht, als etwas, das man tut. Daher dachte ich, können wir ja hier 
auch mal drüber reden. ;-)

Ich frage mich, wie ihr, die ihr im *Team* arbeitet, für einen möglichst 
ganzheitlichen Ansatz von Dokumentation sorgt?

Dokumentation umfaßt für mich verschiedene Aspekte in der 
Softwareentwicklung:

*** Dokumentation für den Endandwender ***
(bspw. PDF zum Download aus der Weboberfläche der Software)

*** Quellcodedokumentation ***
(hier nehmen wir phpdoc nach PEAR-Standards, zur Generierung der 
API-Dokumentation testen wir gerade verschiedene Systeme wie 
PHPDocumentor, phpEdit etc.)

*** Programmabläufe, Use-Cases ***
(UML-Programme, teils Export von Flußdiagrammen in Grafiken zur 
Verwendung als Dokumentation innerhalb anderer Dokumente oder als Ablage 
im Filesystem des Projektes)

*** Dokumentation des Softwareentwicklungsprozesses selbst ***
(Bugtracker für Bugs, Kundenwünsche, Weiterentwicklungsideen etc., 
Dateikommentare im CVS, Historie unterschiedlicher Versionen, 
Voraussetzungen die das Programm macht -> PHP>4.2.x, PEAR-Klasse A,B,C, 
mod-rewrite etc.)

*** Dokumentation projektübergreifender Lösungen ***
(teils bestehendes Intranet, Wiki?)

*** Projektbezogene Kommunikation der Entwickler/Kunden ***
(Mails, Mailinglisten, teils Projektmanagementtools online mit 
Todo-Listen etc.)

*** weitere? was muss noch dokumentiert werden? ***

Was mir fehlt, ist wie gesagt ein ganzheitlicher Ansatz. Das sind alles 
Systeme, die eher nebeneinander stehen, es fehlt bspw. eine zentrale 
Suchmöglichkeit. Eventuell könnte man das über ein erweitertes Wiki 
lösen, in dass man eine solche Suche implementiert und andere Tools 
andocken kann?

Aber ich will das nicht von vornherein zu sehr einschränken, sondern bin 
auf eure Ideen und Erfahrungen gespannt. Momentan ist mir die Struktur 
einfach zu heterogen, teils werden Sachen neu programmiert, weil niemand 
von den bestehenden Lösungen weiß oder die Recherche in verschiedenen 
Projektordnern im Filesystem und unterschiedlichen Systemen länger 
dauert als die Neuentwicklung. Viel Wissen ist auch einfach nur in den 
Köpfen der Leute vorhanden und damit auch nicht immer verfügbar.

Also, wie macht ihr das? Oder wie würdet ihr das gerne machen, seid aber 
selbst schon gestolpert? Was wünscht ihr euch vielleicht, dass es noch 
nicht gibt?

Viele Grüße
André Temme