[php] Dokumentation von/in Software-Projekten

[Björn Schotte]

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

Oder ein help-System, was speziell auf die Software zugeschnitten
ist und kontextsensitive Manual-Abschnitte anzeigt. Zusätzlich vielleicht
noch Videos (z.B. per RoboDemo) in Flash, die zeigen, wie man einzelne
Teile der Software bedient.
 
> *** Quellcodedokumentation ***
> (hier nehmen wir phpdoc nach PEAR-Standards, zur Generierung der 
> API-Dokumentation testen wir gerade verschiedene Systeme wie 
> PHPDocumentor, phpEdit etc.)

phpdoc nach PEAR-Standard, ACK.

> *** Programmabläufe, Use-Cases ***
> (UML-Programme, teils Export von Flußdiagrammen in Grafiken zur 
> Verwendung

Meine Erfahrung hier ist, dass selbst in größeren Projekten mit >500
Leistungstagen keine Zeit für sowas bleibt. Man muß da lieber sehen,
dass man die Präsentationsdeadline des Projektmanagers beim Kunden
nicht reißt und alle benötigten Teile stehen, weil die Projektplanung
mal wieder vor der eigentlichen Abschätzung durch die Entwickler gelaufen
ist ...

Und das ist nicht die Ausnahme, sondern beinahe die Regel. Nein,
keine kleinen Klitschen, sondern Großkonzerne. Weil "wenn's ein
Pflichtenheft nach der Theorie der klassischen SW-Entwicklung gäbe,
würden wir das in Indien erledigen lassen" und "Der andere Anbieter
mit seinem Java-Trupp wollte 2000 Leistungstage veranschlagen und
hätte damit die Kosten für den Endkunden von 6 auf 7 Stellen hochgetrieben"
(und da bin ich mir sicher, wäre UML & Co. mit dran gekommen)

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

Mantis, in das der Endkunde bei der SW-Abnahme in einem in Mantis
getrennt eingestellten Projekt seine Bugs einträgt; manche Kunden
schicken auch nur Excel-Files mit einer Liste der Bugs, die dann
einfach abgearbeitet werden. Oder sie rufen an, und während des
Telefonats werden die Bugs gefixt -> mit entsprechenden Kommentaren
im CVS natürlich.
 
> *** Projektbezogene Kommunikation der Entwickler/Kunden ***
> (Mails, Mailinglisten, teils Projektmanagementtools online mit 
> Todo-Listen etc.)

Mailinglisten, Telefon, Excel-Sheets, Powerpoints mit Screenshots
darin.
 
> Was mir fehlt, ist wie gesagt ein ganzheitlicher Ansatz.

Den gibt es meiner Ansicht nach nicht. Jeder Kunde hat eine andere
Arbeitsweise. Wir passen uns an den Kunden an, nicht umgekehrt. D.h.
wenn der Kunde uns unbedingt seine Support-Requests am Telefon stellen
will, dann stellt er die am Telefon, und nicht per Webinterface. Wenn
er seine Bugreports per Excel-Liste zu uns schickt, dann schickt er
sie per Excel-Liste, und nicht per externem Mantis-Login.

Dass es dann natürlich intern einen Kanalisierungsweg gibt, der
es dem ganzen Team ermöglicht, Bescheid zu wissen, ist klar.

My 0,02 EUR, Björn.
-- 
ThinkPHP / rent-a-phpwizard                   bjoern at thinkphp.de
Sedanstraße 27                             Tel: 0931 / 78 43 804
97082 Würzburg                             Fax: 0931 / 78 43 795
                 http://blog.rent-a-phpwizard.de/