Arbeitsmethodik, Dokumentation

[Alexander (HH)]

Moin Moin!

Es gibt das PHPDoc-Format.

Mir war doch so, aber mir fiel der Begriff nicht ein. Müffelt allerdings sehr nach Javadoc.

Und wie kann ich einen Gesamtüberblick führen? So dass ich z.B. zentral aufgeführt habe, was ich alles zum nächsten Update des Produktivservers hochladen muss?

Ein Wiki wäre eine Möglichkeit (siehe Trac).

Nein. Das ist wieder fehleranfälliges, manuelles Gefrickel. Um Updates soll sich der Rechner selbst kümmern, die nötigen Schritte kann der viel schneller rausrechnen als Du das von Hand kannst.

Oh, und wo wir gerade beim Wiki sind: Wikis *können* das Schreiben der Doku an eine Community auslagern. Das klappt bei der englischen Wikipedia recht gut, bei der deutschen mäßig, bei anderen Projekten wie OpenWRT gar nicht. Einfach ein leeres Wiki auf die Projekt-Seite im WWW zu stellen und zu hoffen, dass die User anfangen zu dokumentieren, klappt nicht. Und die Texte der Code-Sklaven sind auch meistens keine Freude.

Für ein kleines Entwickler-Team kann ein internes Wiki funktionieren, muß aber nicht. Es erfordert auf jeden Fall Disziplin, wenn man nicht am Ende vor einem großen Haufen ungepflegtem Text stehen will.

Entsprechend mehr Aufwand macht es, ein öffentliches Wiki nützlich zu halten.

Mich nervt der Trend vieler Projekte, vorhandene Dokumentation zu einem Wiki zu verwursten und auf Contributers zu hoffen, mittlerweile extrem. Wenn ich mir irgendwelche Projekt-Sources herunterlade, sei es aus SVN/git/... oder als Archiv, erwarte ich, dass die Dokumentation erstens bestandteil des Downloads ist und zweitens den Stand des Downloads dokumentiert.

Wenn ich das Bedürfnis habe, an der Doku mitzuwirken, kann ich den Entwicklern Patches schicken.

Alexander