Arbeitsmethodik, Dokumentation

[johny7]

Moin allerseits,

ich sitze an einem größeren Projekt, das wohl noch bis zum Sommer weiter läuft. (Ich Programmiere in PHP mit MySQL ;-)
Als Editor hat mir bisher Notepad++ vollkommen ausgereicht. Dagegen habe ich ein Problem bei der Übersicht. Bei den vielen Dateien kommt es vor, dass man beim Update die Übersicht verliert. Oder man vergisst mal ein Datenbank-Insert. Wir haben ein Update-System, welches läuft, solange man alle Änderungen korrekt angibt (die Dateiänderungen werden automatisch erfasst, nur Änderungen der Datenbank müssen per Hand angegeben werden).

Ich bin kein Profi sondern Quereinsteiger im Betrieb. Kann mir jemand gute Quellen liefern, um in das Projektmanagement von Software-Entwicklung ein zu steigen? Die technischen Inhalte habe ich mir autodidaktisch (mit Hilfe von SelfHTML) erworben, ich denke, Projektmanagement kann man auch selbst lernen. Ich bräuchte nur wirklich einschlägige Quellen, auf die man sich verlassen kann (so wie auf SelfHTML damals).

Ich bin für alle Hinweise dankbar.

Grüße, JN

[Alexander (HH)]

Moin Moin!

Subversion, git, mercury o.ä., damit Du deine Sources und Scripte verwalten kannst

Bugzilla ö.ä. für's Bug- und Feature-Tracking

(Trac faßt beides und noch einige andere Extras zusammen, z.B. ein Wiki)

Datenbank-Schema-Versionierung und automatische Up-/Downgrade-Scripts (siehe z.B. Pg::DatabaseManager für das Prinzip)

Makefiles oder Batches für automatische Installation / Updates / Downgrades

Mach nichts manuell, was Du automatisch laufen lassen kannst. Die Automatik kannst Du immer nachvollziehen, übermüdetes Gefrickel tief in der Nacht nicht.

Niemals auf dem Produktivsystem testen. Du hast Idealerweise vier Systeme:

Produktion -- wird nur automatisiert angefaßt, geht nicht kaputt

Staging -- Kopie der Produktion, der letzte Qualitätstest vor Produktion, geht idealerweise nicht kaputt, falls doch: zurück zum Test, Bugs beheben. Schnell wieder herstellbar. Wird unmittelbar vor dem Test auf den Stand der Produktion gebracht.

Test -- Kopie der Produktion, ausdrücklich zum Testen, geht regelmäßig kaputt. Schnell wieder herstellbar. Wird gelegentlich (vor und nach jedem Release) wieder auf den Stand der Produktion gebracht.

Development -- irgendwann mal (nach jedem Release) Kopie der Produktion, Entwicklungssystem, chronisch kaputt, schnell wiederherstellbar.

Staging und Test können virtuelle Maschinen sein, da bietet sich die Snapshot-Funktion zur schnellen Wiederherstellung an. Development kann auch eine VM sein, aber Repository (Subversion) und Bugtracking (Bugzilla) liegen außerhalb der VM.

Dokumentation: Je nach Kundenwunsch. ;-) Minimal so viel, dass Dein zukünftiges Selbst nie das Bedürfnis entwickelt, eine Zeitmaschine zu entwickeln, um in die Vergangenheit zu reisen und Deinem aktuellen Selbst wegen der Qualität und Quantität von Code und Dokumentation Schmerzen zuzufügen.

Besser so viel, dass Du das komplette Projekt an jemand anderen übergeben kannst.

Ideal:

Nur, was wirklich absolut und ohne jede Diskussion sofort offensichtlich ist, bleibt undokumentiert, z.B. $y=$x*$x;. Insbesondere, wenn Du trickst, Seiteneffekte nutzt, von bestimmten Voraussetzungen ausgehst, gehört minimal ein Kommentar in den Code.

$x=$x+1; # $x um 1 erhöhen

... ist redundanter Schrott.

# select kann hier nur maximal einen Datensatz liefern, weil die Spalte XYZ unique ist

... ist wesentlich besser.

Noch besser ist, wenn Du zu jedem Stück Programm noch eine richtige Dokumentation schreibst und die mit dem Programm synchron hältst. Die Doku gehört dann natürlich mit den Sources ins Repository.

Perls POD erlaubt es, die Dokumentation gleich mit in den Code zu schreiben und in nahezu beliebigen Formaten (man-Page, HTML, TeX, PDF, ASCII, ...) zu konvertieren.

Javadoc generiert Teile der Dokumentation sogar selbst, kann aber ohne größere Verrenkungen nur gruseliges HTML generieren.

Anforderungen, Entwürfe, Datenbank-Schemata, Algorithmen solltest Du natürlich auch dokumentieren und archivieren.

Aus Erfahrung mit gewachsenen Projekten: Wenn Du nicht am ersten Tag anfängst zu dokumentieren und das konsequent durchziehst, wirst Du das Projekt nie auch nur näherungsweise vollständig Dokumentiert haben.

"Doku schreib ich hinterher" funktioniert nicht. Nicht für eigene kleine Projekte und schon gar nicht für große Kundenprojekte. Denn Du wirst die Doku immer weiter vor Dir her schieben und irgendwann feststellen, dass Du Unmengen von undokumentiertem Code hast. Und wir alle wissen, dass Code nur ein ganz kleiner Teil eines Projektes ist, die Doku braucht viel mehr Zeit.

An dem Punkt hat mein Vorgänger übrigens gekündigt, wir stehen hier mit 10 Jahren undokumentierter (und unqualifizierter) Bastelei an drei Projekten und alles brennt. Ich wünsch' mir zu Weihnachten übrigens nur eine Voodoo-Puppe mit seinem Gesicht ... ;-)

Alexander

[johny7]

Moin allerseits,

danke erst mal für die vielen Ratschläge.

Subversion, git, mercury o.ä., damit Du deine Sources und Scripte verwalten kannst

Yep.

Bugzilla ö.ä. für's Bug- und Feature-Tracking

(Trac faßt beides und noch einige andere Extras zusammen, z.B. ein Wiki)

Aha, interessant

Datenbank-Schema-Versionierung und automatische Up-/Downgrade-Scripts (siehe z.B. Pg::DatabaseManager für das Prinzip)

Makefiles oder Batches für automatische Installation / Updates / Downgrades

Das Update-System ist schon automatisiert

Mach nichts manuell, was Du automatisch laufen lassen kannst. Die Automatik kannst Du immer nachvollziehen, übermüdetes Gefrickel tief in der Nacht nicht.

Niemals auf dem Produktivsystem testen. Du hast Idealerweise vier Systeme:

Produktion -- wird nur automatisiert angefaßt, geht nicht kaputt

Staging -- Kopie der Produktion, der letzte Qualitätstest vor Produktion, geht idealerweise nicht kaputt, falls doch: zurück zum Test, Bugs beheben. Schnell wieder herstellbar. Wird unmittelbar vor dem Test auf den Stand der Produktion gebracht.

Test -- Kopie der Produktion, ausdrücklich zum Testen, geht regelmäßig kaputt. Schnell wieder herstellbar. Wird gelegentlich (vor und nach jedem Release) wieder auf den Stand der Produktion gebracht.

Development -- irgendwann mal (nach jedem Release) Kopie der Produktion, Entwicklungssystem, chronisch kaputt, schnell wiederherstellbar.

Staging und Test können virtuelle Maschinen sein, da bietet sich die Snapshot-Funktion zur schnellen Wiederherstellung an. Development kann auch eine VM sein, aber Repository (Subversion) und Bugtracking (Bugzilla) liegen außerhalb der VM.

Aha. Was spricht gegen drei Systeme? Ein Entwicklungsserver, eine Live-Umgebung und die Produktiv-Server?

Dokumentation: Je nach Kundenwunsch. ;-) Minimal so viel, dass Dein zukünftiges Selbst nie das Bedürfnis entwickelt, eine Zeitmaschine zu entwickeln, um in die Vergangenheit zu reisen und Deinem aktuellen Selbst wegen der Qualität und Quantität von Code und Dokumentation Schmerzen zuzufügen.

Besser so viel, dass Du das komplette Projekt an jemand anderen übergeben kannst.

Ideal:

Nur, was wirklich absolut und ohne jede Diskussion sofort offensichtlich ist, bleibt undokumentiert, z.B. $y=$x*$x;. Insbesondere, wenn Du trickst, Seiteneffekte nutzt, von bestimmten Voraussetzungen ausgehst, gehört minimal ein Kommentar in den Code.

$x=$x+1; # $x um 1 erhöhen

... ist redundanter Schrott.

# select kann hier nur maximal einen Datensatz liefern, weil die Spalte XYZ unique ist

... ist wesentlich besser.

Noch besser ist, wenn Du zu jedem Stück Programm noch eine richtige Dokumentation schreibst und die mit dem Programm synchron hältst. Die Doku gehört dann natürlich mit den Sources ins Repository.

So! Das möchte ich. Ich weiß nur noch nicht, wie ich das anstellen soll! Hat jemand schon Lösungen? Wie kann ich parallel zum PProgrammieren dokumentieren? Und zwar in PHP? Am Liebsten würde ich gleich nach dem Schreiben der Funktion erklären, warum. Aber so viele Kommentare im Quellcode machen ihn unübersichtlich. Wie kann ich so eine History jeder Datei führen? Lohnt es sich, Excel-Tabellen dafür zu verwenden? So dass man auch Datum und Autor eintragen kann zu jeder Änderung?

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?

Perls POD erlaubt es, die Dokumentation gleich mit in den Code zu schreiben und in nahezu beliebigen Formaten (man-Page, HTML, TeX, PDF, ASCII, ...) zu konvertieren.

Ich brauch es halt für PHP und HTML sowie MySQL

Javadoc generiert Teile der Dokumentation sogar selbst, kann aber ohne größere Verrenkungen nur gruseliges HTML generieren.

Ja, am Besten, man kann die Doku in verschiedenen Formaten bekommen...

Anforderungen, Entwürfe, Datenbank-Schemata, Algorithmen solltest Du natürlich auch dokumentieren und archivieren.

Wie? In OpenOffice-Dokumenten? Wie strukturiert und formatiert?

Aus Erfahrung mit gewachsenen Projekten: Wenn Du nicht am ersten Tag anfängst zu dokumentieren und das konsequent durchziehst, wirst Du das Projekt nie auch nur näherungsweise vollständig Dokumentiert haben.

Davor habe ich Angst. Deshalb frage ich lieber jetzt nach!

"Doku schreib ich hinterher" funktioniert nicht. Nicht für eigene kleine Projekte und schon gar nicht für große Kundenprojekte. Denn Du wirst die Doku immer weiter vor Dir her schieben und irgendwann feststellen, dass Du Unmengen von undokumentiertem Code hast. Und wir alle wissen, dass Code nur ein ganz kleiner Teil eines Projektes ist, die Doku braucht viel mehr Zeit.

An dem Punkt hat mein Vorgänger übrigens gekündigt, wir stehen hier mit 10 Jahren undokumentierter (und unqualifizierter) Bastelei an drei Projekten und alles brennt. Ich wünsch' mir zu Weihnachten übrigens nur eine Voodoo-Puppe mit seinem Gesicht ... ;-)

Das will ich vermeiden.

Noch eins: Lohnt es sich, eine IDE wie z.B. Eclipse zu verwenden? Kann man damit die Dokumentation vereinfachen? Oder gibt es eine bessere Alternative? Oder reicht Notepad++?

Grüße, JN

[dedlfix]

Hi!

Noch besser ist, wenn Du zu jedem Stück Programm noch eine richtige Dokumentation schreibst und die mit dem Programm synchron hältst. Die Doku gehört dann natürlich mit den Sources ins Repository.
So! Das möchte ich. Ich weiß nur noch nicht, wie ich das anstellen soll! Hat jemand schon Lösungen? Wie kann ich parallel zum PProgrammieren dokumentieren? Und zwar in PHP? Am Liebsten würde ich gleich nach dem Schreiben der Funktion erklären, warum. Aber so viele Kommentare im Quellcode machen ihn unübersichtlich. Wie kann ich so eine History jeder Datei führen?

Es gibt das PHPDoc-Format. Außerdem gibt es Editoren und IDEs mit Codefolding, da kannst du auch die Kommentare ausblenden, wenn du sie nicht sehen willst.

Eine History hast du mit dem Versionsverwaltungstool.

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

Noch eins: Lohnt es sich, eine IDE wie z.B. Eclipse zu verwenden? Kann man damit die Dokumentation vereinfachen? Oder gibt es eine bessere Alternative? Oder reicht Notepad++?

Zusammen mit einem ordentlich gepflegten PHPDoc kann Eclipse (und auch andere PHP-IDEs) schon beim Programmieren behilflich sein, weil es die PHPDoc-Kommentare als Tooltips anzeigen kann. Notepad++ kann das nicht.

Lo!

[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

[dedlfix]

Hi!

Es gibt das PHPDoc-Format.
Mir war doch so, aber mir fiel der Begriff nicht ein. Müffelt allerdings sehr nach Javadoc.

Ja.

Oh, und wo wir gerade beim Wiki sind: Wikis *können* das Schreiben der Doku an eine Community auslagern.

Darum geht es hier vermutlich nicht, aber wenn man schon Trac aufsetzt, kann man es auch gleich für die Dokumentation nutzen.

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

Das geht nur dann effizient, wenn auch die Dokumentation als Quelltext vorliegt. Mit einer CMS-gepflegten sieht das schon anders aus. Letzlich muss man sicher den Aufwand gegeneinander aufwiegen. Es ist ja nicht nur, dass du nach der Korrektur einen Patch erstellen muss, du wirst ihn vor dem Absenden auch noch mit einem Anschreiben versehen. Und am anderen Ende braucht es Ressourcen, den Patch einzupflegen.

Lo!

[Alexander (HH)]

Moin Moin!

Makefiles oder Batches für automatische Installation / Updates / Downgrades Das Update-System ist schon automatisiert

Inklusive Rollback (à la "oops, war nicht so gemeint, zurück zum alten Stand")?

Du hast Idealerweise vier Systeme:

Produktion -- [...]

Staging -- [...]

Test -- [...]

Development -- [...] Aha. Was spricht gegen drei Systeme? Ein Entwicklungsserver, eine Live-Umgebung und die Produktiv-Server?

Zwischen den letzten beiden sehe ich keinen begrifflichen Unterschied.

Welchen aus meiner Liste möchtest Du streichen? Staging oder Test? Der Charme einer Staging-Maschine ist, dass Du jederzeit eine Simulation des Produktivsystems hast (z.B. um "mal eben schnell" eine Präsentation zu zaubern, die der Chef bzw. Kunde vor 4 Wochen seinem Kunden bzw. Chef zugesagt hat, ohne Dich zu informieren). Natürlich kannst Du Staging und Test zusammenlegen, dann mußt Du aber nach erfolgreichen Tests die Test-Maschine erst einmal 100% auf den Produktionsstand bringen, und dann noch einmal das finale Update für das jeweilige Release dort testen.

Damit entsprechen die Server aber nicht dem Arbeitsablauf: Du programmierst auf der Development-Maschine (davon gibt es eine pro Code-Sklaven), irgendwann nennst Du einen Stand Release Candidate, baust ein Release, schmeißt das auf den Test-Server (einer für alle Code-Sklaven), und läßt es dort Amok laufen. Das wiederholst Du, bis ein Release Candidate den Test-Server nicht mehr schrottet und damit offiziell zum Release befördert ist. Das offizielle Release übergibst Du dann dem Admin (der Du in Personalunion auch sein kannst), der testet es noch einmal auf dem Staging-Server und spielt es dann in den Produktivserver ein. Demoliert das offizielle Release den Staging-Server, wird der Admin Dir kräftig den Kopf zurechtrücken, anschließend markierst Du das Release als blöde Idee und baust ein NEUES Release, während der Admin die Scherben des Staging-Servers zusammenfegt.

Plattenplatz ist billig, und VMs brauchen keine zusätzlichen Flächen. Was willst Du einsparen? Zwei Container weiter steht ein "erbeuteter" Server mit ordentlich RAM, auf dem laufen zur Zeit sieben VMs, notfalls auch mal parallel. Außerdem arbeitet der Server noch als SVN-Repository, Bugzilla-Datenbank, und (ein wenig, aufgrund unserer LAN-Struktur) als Fileserver für den Transfer zwischen realer und virtualisierter Welt.

Auf einem halbwegs aktuellen Desktop-System sind zwei parallel laufende VMs übrigens auch kein großes Thema.

Dokumentation: [...] Noch besser ist, wenn Du zu jedem Stück Programm noch eine richtige Dokumentation schreibst und die mit dem Programm synchron hältst. Die Doku gehört dann natürlich mit den Sources ins Repository. So! Das möchte ich. Ich weiß nur noch nicht, wie ich das anstellen soll! Hat jemand schon Lösungen? Wie kann ich parallel zum PProgrammieren dokumentieren? Und zwar in PHP? Am Liebsten würde ich gleich nach dem Schreiben der Funktion erklären, warum.

Ja, kann ich nachvollziehen. Das ist die "dunkle Seite der Macht".

Nach der reinen Lehre fängst Du mit einem Pflichtenheft an, daraus entwickelst Du ein grobes Konzept, daraus wiederum einen detailierten Plan. Drei Dokumente, die alle schon im SVN (oder git, hg, whatever ...) liegen, bevor Du auch nur eine Zeile Code schreibst.

Pflichtenheft: Was soll das Ding können? Unter welchen Bedingungen? Usw. Das Pflichtenheft kommt vom Kunden bzw. wird zusammen mit dem Kunden entwickelt.

Konzept: Wie setze ich das Pflichtenheft ganz grob um? Ablaufdiagramme wären hier zu finden, und Skizzen, wie Klassen / Module miteinander interagieren, wie Daten auf Tabellen aufgeteilt werden. Usw.

Plan: Wie setze ich das Konzept im Detail um? Hilfsklassen, Hilfstabellen, Methoden- und Funktionsnamen und -parameter, Beschreibungen, was Module / Klassen und Funktionen / Methoden im Detail machen sollen. Usw.

Notfalls unterteilst Du Konzept und Plan nocheinmal jeweils in grob und fein. Mit etwas Erfahrung kannst Du aus dem Grobkonzept schon abschätzen, wie viel Arbeit auf Dich zukommt, in der Größenordnung Wochen / Monate. Mit jedem Schritt kann Deine Schätzung besser werden, mit dem Feinplan kannst Du pro Funktion sagen, wie viele Minuten / Stunden Du brauchen wirst, und entsprechend aufsummieren.

Am Ende des Plans steht Dein fertiges Programm, so weit ausgearbeitet, dass Du nur noch von Deutsch / Englisch nach Perl, Java, PHP, SQL, HTML, Javascript, ... übersetzen mußt.

Wenn Du den Plan fertig hast, setzt Du als Einzelkämpfer den Entwickler-Hut ab und legst die Fußkette des Code-Sklaven an.

Der Job des Code-Sklaven ist wirklich nur noch übersetzen und interpretieren der feinen Nuancen, zwischen den Zeilen des Plans stehen.

Aber so viele Kommentare im Quellcode machen ihn unübersichtlich.

Nicht, wenn Du begriffen hast, das Kommentare keine Dokumentation sind. Manchen Leuten kann man das leicht beibringen, um andere Leute davon zu überzeugen, braucht man Werkzeuge aus mittelalterlichen Folterkammern.

Dokumentation schreibst Du nicht in Kommentare, sondern in ein eigenes Dokument, im Sonderfall POD notfalls auch in einen eigenen Abschnitt (am Ende) der Source-Datei.

Wie kann ich so eine History jeder Datei führen? Lohnt es sich, Excel-Tabellen dafür zu verwenden? So dass man auch Datum und Autor eintragen kann zu jeder Änderung?

Wozu doppelte Arbeit? SVN (git, hg, ...) kümmert sich um die Historie, komplett mit Datum und Autor und allen vorgenommenen Änderungen und Commit-Kommentaren.

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?

Darum kümmern sich Deine Scripte, das machst Du eben NICHT von Hand.

svn diff -r $oldRev:$newRev | grep Index

... kann ein Ansatz sein, auf dem ein Script aufsetzt.

Noch brutaler:

rm -rf tmpdir svn export [e-mail]:/svn/repos/projectX/tag/release-$Release tmpdir rsync -avzx --delete-during --rsh=ssh tmpdir/ [e-mail]/srv/www/projectX/ ssh [e-mail] make -C /srv/www/projectX after-rsync

Das lief fast exakt so sehr lange bei meinem letzten Arbeitgeber, einfach durch Aufruf von "make upload-production". Der gesamte Code liegt im SVN, den schmeißt svn export in ein frisches, leeres Verzeichnis. rsync schiebt den Code auf den Ziel-Server (je nach make-Target test, staging oder production), ohne dabei unnötig Bandbreite zu verschwenden, der abschließende Aufruf von make via ssh auf dem Ziel-Server sorgt dafür, das alle notwendigen Arbeiten automatisch stattfinden, z.B. DB-Updates, Restart persistenter Prozesse, usw.

Prinzipiell kannst Du nach dem svn export auch ein TAR / ZIP aus tmpdir bauen, das irgendwie anders zum Server schaffen und dort das Update-Script (hier: make after-rsync) laufen lassen.

Perls POD erlaubt es, die Dokumentation gleich mit in den Code zu schreiben und in nahezu beliebigen Formaten (man-Page, HTML, TeX, PDF, ASCII, ...) zu konvertieren. Ich brauch es halt für PHP und HTML sowie MySQL

Und? Wo ist das Problem? Finde ein brauchbares System, oder entwickle ein Neues. Zwei hab ich Dir vorgeschlagen, und Google wird Dir sicherlich noch ein paar mehr ausspucken.

Wenn Du Dich mit POD anfreunden kannst, hast Du drei Möglichkeiten:

• POD-Datei neben der zu dokumentierenden Datei (foo.php => foo.pod, exakt wie in Perl auch gerne praktiziert, oder foo.php => foo.php.pod)
• baue POD in die Datei ein und filter es wieder aus, bevor andere Tools mit dem Dateiinhalt arbeiten. Das hab ich neulich mal für SQL gebaut, im Kern unter 20 Zeilen Perl-Code. Die Kombination aus POD und SQL hab ich stumpf name.podsql genannt, Make und Perl haben daraus eine name.pod und eine name.sql generiert, und in einem weiteren Schritt aus der name.pod noch eine name.html.
• baue POD so in die Datei ein, dass es vom nächsten System ignoriert wird, z.B. als Kommentar oder als Dummy-Stringkonstante. Bei HTML könntest Du POD stumpf in <!-- --> verpacken, allerdings solltest Du das vielleicht nicht ungefiltert ins WWW stellen.

Javadoc generiert Teile der Dokumentation sogar selbst, kann aber ohne größere Verrenkungen nur gruseliges HTML generieren.

Ja, am Besten, man kann die Doku in verschiedenen Formaten bekommen...

Eben. Das ist für mich immer ein Argument für POD und gegen Javadoc und Derivate gewesen.

Anforderungen, Entwürfe, Datenbank-Schemata, Algorithmen solltest Du natürlich auch dokumentieren und archivieren. Wie? In OpenOffice-Dokumenten?

Office-Dokumente sind schwer zu diff-en, weil Binärmüll statt Klartext. Neuere Office-Formate sind zwar "nur" noch gezippte Sammlungen von viel XML und ggf. ein paar Bildern, aber auch die stellst Du als Binäres Archiv ins SVN und kannst dann ohne viel Theater keine brauchbaren Diffs bekommen.

Daher bevorzuge ich auch da POD oder notfalls HTML. Plain Text ist auch nicht schlimm. Du kannst auch TeX oder LaTeX für "hübsche" Dokumente nehmen, gerne auch wenn Du dich mit Formeln rumschlagen mußt (das kann TeX richtig gut).

Dazu ein Makefile, um aus POD, Plain Text, (La)Tex "vorstandstaugliche" Dokumente wie HTML oder PDF zu erzeugen.

HTML hat außerdem die Vorteile, dass Du erstens mit einem zentralen Stylesheet für ein gutes Aussehen der Doku sorgen und zweitens die einzelnen Bestandteile miteinander verlinken kannst -- selbst wenn einzelne Dokumente Plain Text, PDF oder gar eine Grafik sind.

Wie strukturiert

Wie es notwendig ist. Zum Beispiel mit einem doc-Verzeichnis im Projekt. Vielleicht noch ein zweites devel-doc-Verzeichnis, um Dokumentation für Kunde / End-Benutzer und interne Dokumentation zu trennen. Darunter nach Bedarf unterverzeichnisse.

und formatiert?

title, h1, h2, h3, ul, ol, dl?

Aus Erfahrung mit gewachsenen Projekten: Wenn Du nicht am ersten Tag anfängst zu dokumentieren und das konsequent durchziehst, wirst Du das Projekt nie auch nur näherungsweise vollständig Dokumentiert haben. Davor habe ich Angst. Deshalb frage ich lieber jetzt nach!

Fang an mit Doku. Code fällt hinten von ganz alleine raus. Siehe oben.

"Doku schreib ich hinterher" funktioniert nicht. [...]

An dem Punkt hat mein Vorgänger übrigens gekündigt, wir stehen hier mit 10 Jahren undokumentierter (und unqualifizierter) Bastelei an drei Projekten und alles brennt. Ich wünsch' mir zu Weihnachten übrigens nur eine Voodoo-Puppe mit seinem Gesicht ... ;-) Das will ich vermeiden.

Guter Plan.

Noch eins: Lohnt es sich, eine IDE wie z.B. Eclipse zu verwenden?

Ich kann mich mit Eclipse nicht so wirklich anfreunden. Andere wollen nie wieder ohne arbeiten. Wie auch emacs kannst Du Eclipse wahnsinnig aufbohren, wobei emacs da gerüchteweise noch etwas weiter anpaßbar ist. Eclipse braucht Java-Klassen, emacs kannst Du per Lisp-Scripting erweitern. Beides nicht sonderlich attraktiv ... ;-)

Kann man damit die Dokumentation vereinfachen?

Wie? Glaubst Du, Eclipse oder emacs schreibt die Doku für Dich? Ein HTML-Editor-Mode wäre natürlich hilfreich, wenn Du Deine Doku in HTML schreiben willst. Entsprechend ein POD-Mode für POD-Doku, LaTex-Mode, ...

Oder gibt es eine bessere Alternative? Oder reicht Notepad++?

Prinzipiell reicht Notepad++, den Rest kannst Du auch mit Scripten auf einem Linux-System erledigen. Allerdings gibt es leistungsfähigere Editoren, die Dir das Leben leichter machen. UltraEdit beispielsweise.

Ich persönlich bin nicht auf einen Editor festgelegt. Auf Windows-Systemen nehme ich meistens UltraEdit, gelegentlich auch Notepad++, wenn alle Stricke reißen auch mal das originale Notepad. Auf Linuxen hab ich meistens joe, notfalls nehme ich auch irgendeinen vi-Clone.

Alexander