Geht es mit SELFHTML bergab?

[molily]

Hallo,

Hm, eine Kommentarmöglichkeit ist doch nicht automatisch gleich ein Wiki?

Jein.
Kommentare schreiben die Doku dann fort, ergänzen sie womöglich um etwas, was eigentlich direkt in der Doku hätte drinstehen müssen. Das ist die Gefahr. Was ist nun besser, fortschreiben (ergänzen) von wichtigen Aspekten durch Kommentare oder umschreiben (einarbeiten, korrigieren) wie in einem Wiki? Dann m.M.n. eher umschreiben. Darauf muss es sowieso hinauslaufen bei Folgeversionen - eine Synchronisierung zwischen Text und Kommentaren. Warum funktioniert das momentan nicht (prinzipiell) über die üblichen Feedback-Mechanismen und Ergänzungsangebote wie SELFHTML aktuell?

Im PHP-Manual haben sich die Nutzerkommentare sehr oft als hilfreich erwiesen und vielerorts Mängel in den eigentlichen Beschreibungen ausgebessert. Ich sehe kaum einen Grund, warum dies in der SELFHTML-Doku nicht auch so sein sollte.

Natürlich sind die Kommentare in der PHP-Doku hilfreich. Das ist aber kein Argument. Das PHP-Manual zeigt bereits, warum eine Kommentarfunktion (auch) ein gefährliches Konzept ist aus Sicht der Planung einer Doku.

Die Kommentare des PHP-Manuals bestehen zu einem großen Teil aus zwei Typen:

1. Sie kompensieren konzeptionelle Fehler in der Doku,
a. weil diese im Referenzteil schlicht fehlerhaft und lückenhaft ist,
b. weil wichtige Beispiele, essentielle Hintergrundinfos, Querverweise sowie Häufig gestellte Fragen darin nur spärlich vorkommen.

2. Es handelt sich um nützliche Scriptschnipsel.

Dies zeigt m.M.n., dass die PHP-Doku Schwächen hat. Wenn ich also das Konzept einer Doku plane, plane ich es so, dass ich eben *keine* Kommentarfunktion brauche, die *diese* entscheidenden Aufgaben mehr schlecht als recht löst. Ich würde mir zum Ziel setzen, die Doku eben nicht so zu schreiben, dass sie nicht dermaßen lückenhaft ist und an Beispielen mangelt.

Und was Scriptschnipsel angeht, so müsste man sich ein besseres System ausdenken. Dafür ist eine offene Kommentarfunktion Käse, unter anderem weil oft eine Diskussionsstruktur entsteht, weil jemand das Script eines anderen ergänzt oder verbessert.

Sprich, für eine Kommentarfunktion gibt es selbstverständlich gute Argumente, wenn man eine mangelhaften Doku als festen Ausgangspunkt annimmt. Das kann aber nicht die Planung von SELFHTML 9 sein. Man müsste sich also andere Zwecke für Kommentare überlegen als die genannten. Die PHP-Doku kann nicht als Beispiel (»Seht, da funktioniert es prächtig!«) dienen.

Mathias