[php] Dokumentation von/in Software-Projekten

[Andre Temme]

Hallo Björn,

(sind wir die einzigen beiden die wenigstens über Doku reden? ;-) )

Björn Schotte schrieb:
> 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.

Ja, haben wir auch schon mit gearbeitet, gute Ergänzung der Liste, danke 
- macht m.E. nicht in jeder Web-Software Sinn, kann aber sinnvoll sein, 
und kommt auch meistens gut an bei den Endandwendern.

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

Klar, Zeitnot ist mir auch reichlich bekannt ;-) Gerade deshalb aber 
denke ich, ist ein einheitliches Dokumentationssystem sinnvoll - ich 
will ja insgesamt Zeit sparen, und nicht Zeit verschwenden. Bei uns geht 
aber gerade wegen der uneinheitlichen Dokumentationslandschaft viel Zeit 
verloren.

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

Schwierige Argumentation. Aus der Erfahrung gebe ich dir Recht, die 
Praxis sieht oft so aus. Das bedeutet aber nicht, dass es so sein muss, 
bzw. dass es so optimal ist. UML (oder einfache Flußdiagramme) können 
eine Menge Zeit sparen, z.B. bei der Einarbeitung neuer Programmierer in 
bestehende Projekte oder bei der Kosten-/Machbarkeits-Folgeschätzung von 
  Weiterentwicklungen bestehender Projekte.

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

Haben wir auch mal getestet, Mantis macht ab einer gewissen Größe der 
Software Sinn, für kleine bis mittelgroße Projekte ziehen wir eine 
Eigenentwicklung vor, die auch von der Nomenklatur der verschiedenen 
Bugstati und dergleichen besser zu uns paßt. Excel/Telefon und andere 
"propriätere Formate" sind Tatsache, wohl wahr - dann will ich die und 
die Telefonprotokolle eben auch zentral durchsuchen können!

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

Und da muss man m.M. nach ansetzen. Klar ist die Landschaft heterogen, 
da bin ich ja auch schon beim Erstellen obiger Liste von ausgegangen, 
das kann aber doch nicht bedeuten, dass man deshalb nicht zu zentralen 
Lösunden kommen kann?
Gerade PHP bspw. eignet sich doch ideal zum Zugriff auf verschiedenste 
Systeme, daher auch meine Idee mit einem erweiterten Wiki:

Es gibt ja mittlerweile Suchindexer, die verschiedene MS-Office-Formate, 
  PDF, HTML, Text und dergleichen mehr durchsuchen und indizieren können 
(XML?). Schnittstellen zu PHP sind m.W. auch vorhanden. Generierung von 
PDF als Dokuformat aus HTML-Seiten geht mit PHP auch. Datenbank von 
Mantis und anderen Systemen durchsuchen geht auch. Anbindung ext. 
Systeme: SOAP etc. Einbindung von UML: Export und Einbindung, vielleicht 
liegt UML sogar bei dem ein oder anderen System schon indizierbar als 
XML vor? Und so weiter und so fort.

Verstehst du (ihr), wo ich hin will? Und vielleicht gibt's ja schon was 
in der Richtung? Falls nicht, ich denke der Bedarf ist groß genug für 
sowas. Vielleicht wird mal ein Produkt draus?

Viele Grüße
André Temme