Wie schreibt ihr Dokumentationen?

[AxlF]

Hallo,

mich würde mal Interessieren, wie, ob, und wieviel Dokumentationen Ihr anfertigt.

Schreibt Ihr nur Kommentare in den Quelltext oder PHPDoc Kommentare?

Fertigt Ihr Dokumentationen für den Endbenutzer an?

Oder was gebt Ihr eurem Auftraggeber, wenn dieser eine Dokumentation von seiner Webseite wünscht?

Gruß,
Alexander

 

[Julia-DD]

Sowas habe ich noch nie gehabt. Wozu braucht der Auftraggeber eine Dokumentation der Seite? Was soll denn da drin stehen? Bin mal ehrlich neugierig.

Julia

 

[AxlF]

Hi Julia,

als Beispiel:

Ich habe ein rel. komplexes Projekt übernommen. Die Seite war wirklich richtig schlecht Dokumentiert. Sehr wenig Kommentare im Quelltext, komplexe Struktur (keine bekannten Konzepte wie MVC, oder Templates), keine zusätzlichen Informationen über irgendetwas.

Das Projekt sollte jetzt von mir gepflegt werden, was ich auch irgendwie gemacht habe. Auf die Problematik, dass ich eigentlich nicht sicher sein kann, wenn ich einen Fehler behebe, nicht 3 neue zu generieren, habe ich hingewiesen. Klar: Das kann man ja auch nicht garantieren, da ich nicht weiß wenn ich eine Funktion ändere, an wievielen Stellen die Funktion anders erwartet wird.

Derselbe Auftraggeber hat nun ein neues Projekt, das er von mir realisiert haben will. Natürlich passiert Ihm das nicht mehr dass er keine Dokumentation (Stichwort: Pflichtenheft) mehr bekommt. Falls dann der Programmierer wechselt, soll der andere genauso gut damit zurechtkommen.

Gruß,
Alexander

 

[Julia-DD]

Ach so.

Hmm. In so einem Fall würde ich
a) den Quelltext, das Template, CSS und was du sonst noch verwendest ganz klar kommentieren, damit man schon beim ersten Blick hinein eine Vorstellung bekommt
b) eine Auflistung der von mir verwendeten Styles, Codes etc machen, thematisch geordnet, eben eine Doku. Kapitel 1: Styles (CSS, Farben etc), Kapitel 2: PHP etc
--> würde ich natürlich in Kalkulation des Preises mit aufnehmen, weil das einen höllischen Mehraufwand bedeutet

Was die Überarbeitung des bestehenden Projektes betrifft: Ich hatte mal einen Kunden, den der Teufel geritten hat und der mit MS Frontpage meine sorgsam geschriebene Seite "geupdated" hat. Nachdem ich dann 3 Monate lang jedes Mal einen Wutanfall bekommen habe, wenn ich etwas gemacht habe (änderte was und an einer anderen Stelle fiel der Code plötzlich ohne ersichtlichen Grund auseinander), habe ich dem Kunden vorgerechnet, dass er langfristig preiswerter kommt, wenn ich ihm die Seite komplett neu aufsetze.

Julia

 

[AxlF]

Ach so.

Hmm. In so einem Fall würde ich
a) den Quelltext, das Template, CSS und was du sonst noch verwendest ganz klar kommentieren, damit man schon beim ersten Blick hinein eine Vorstellung bekommt

Ja, das ist klar. Sollte ja immer so sein, auch wenn keine Doku verlangt wird

b) eine Auflistung der von mir verwendeten Styles, Codes etc machen, thematisch geordnet, eben eine Doku. Kapitel 1: Styles (CSS, Farben etc),

Das lasse ich definitiv weg, weil ich das Design von einem Designer bekommen habe. Wäre ja seine Aufgabe gewesen.

--> würde ich natürlich in Kalkulation des Preises mit aufnehmen, weil das einen höllischen Mehraufwand bedeutet

Ja. Das habe ich auch gesagt und gemacht.

..., habe ich dem Kunden vorgerechnet, dass er langfristig preiswerter kommt, wenn ich ihm die Seite komplett neu aufsetze.

Das habe ich auch so gemacht. Jedoch war es dem Kunden zuviel, weil der Vorgänger anscheinend dasselbe gemacht hatte.


Aber womit schreibst Du das?
Irgendwie will ich nicht akzeptieren das mit Word zu schreiben

 

[Sojus]

Hallo

Ich habe meisstens ein Doukment (Word), in dem ich die Struktur der Seite beschreibe. Was für ein pattern verwendet wird (zbs. MVC). Welche Technologien vorkommen. UseCase Diagramm etc.

Ich habe zbs. ein Diagramm, auf dem die Navigation abgebildet ist, welche Seiten welchen Zweck erfüllen etc.

Wenn eine Datenbank verwendet wird ist ein ERD wichtig in dem die Tabellenstrukturen ersichtlich sind, verwendete Datentypen, eventuelle Datenbank Scripts, views usw.

Bei Projekten mit OOP ein UML Klassendiagramm, welches zbs. das Model abbildet. UML bietet auch noch eine Vielzahl an weiteren Diagrammtypen an, welche, je nach Einsatzgebiet, verwendet werden können.


Im Code selber finde ich Java- bzw PHP-Doc Kommentare sehr wichtig. Damite der Mensch, der das ganze später warten soll auf einen Blick sieht was eine Funktion genau macht. Aus den PHP-Doc Kommentaren umbedingt die HTML Seiten generieren lassen und zur Doukmentation hinzufügen.

Tools, die ich empfehlen kann sind zbs UML oder ERD Programme:
Visio (eignet sich sehr gut für MS Word Dokumente)
DeZign (ERD)
Magic Draw (UML Editor mit community edition)
Visual Paradigm (UML Editor mit community edition)
BOUML (Freeware UML Editor)

mfg