[Talk-de] Code im Wiki dokumentieren
Frederik Ramm
frederik at remote.org
Sa Sep 13 22:19:18 UTC 2008
Hallo,
Markus wrote:
> eigentlich wollte ich ja nur *einladen*, die Möglichkeiten des de:Wiki
> intensiver zu nutzen - und habe dazu eine Hilfe geschrieben, wie man
> Code übersichtlich darstellen kann:
> http://wiki.openstreetmap.org/index.php?title=De:Code_im_Wiki_darstellen
Ich hab halt ein Problem mit Information, die mehrfach kopiert ist und
u.U. nicht aktualisiert wird. Programme werden in erster Linie im Code
dokumentiert. Wenn ich wissen will, welche API-Calls es wirklich gibt,
dann schaue ich in den Rails-Quelltext im SVN. Das ist die Quelle, die
(fast) immer stimmt. Was im englischen Wiki ueber die API-Calls und die
XML-Struktur steht, ist von anderen Leuten geschrieben, es gibt keine
Garantie, dass das noch stimmt oder je gestimmt hat. Die deutschen Texte
wiederum sind in aller Regel von den englischen uebersetzt, und wieder
kann sich der englische laengst geaendert haben.
Klar ist es ein Problem, dass nicht alle englisch lesen koennen und erst
recht nicht alle Rails-Code, aber bitte beruecksichtigt halt bei allem,
was ihr macht, dass die Leser erwarten, dass es "up to date" ist. Ich
hab da leicht reden als Buch-Autor - bei Buechern ist den Lesern klar,
dass das halt vor X Monaten gedruckt wurde und sich daher durchaus
inzwischen was geaendert haben koennte. Beim Wiki ist das nicht klar, im
Gegenteil, die Leute nehmen an, dass das, was da steht, auch stimmt...
> Ja, die auch.
> Genauer:
> - Datenbankstruktur
> - Schema der Attribute
> - Regeln der Schlüssel und Werte
> XML kann das Wiki gut: <source=xml>.
Ab einem gewissen Detaillierungsgrad denke ich, dass wir uns zumindest
den Schritt "Deutsch" wirklich sparen sollten. Jemand, der kein Englisch
kann, der wird unser Rails-API nicht stabil zum Laufen kriegen, da gibt
es zu viele Sachen, wo er auf Englisch nachlesen/fragen/Code schreiben
muss. Da hat es auch keinen Sinn, ihm die Datenbankstruktur auf Deutsch
zu erklaeren. Vor allem eben, weil davon auszugehen ist, dass, wie oben
geschrieben, die Information auf Deutsch immer noch einen Grad
ungenauer, aelter, falscher ist als die auf Englisch.
Wie ueberall gilt natuerlich auch hier: Wer's machen will und wichtig
findet - bitte, macht es. Aber ich fuerchte, es wird eine
Sisyphus-Arbeit, vor allem, weil man von den Programmierern nicht
erwarten kann, dass sie ihren Code zusaetzlich zum SVN auch noch im Wiki
dokumentieren (geschweige denn zusaetzlich zu Englisch noch auf Deutsch...).
Bye
Frederik
--
Frederik Ramm ## eMail frederik at remote.org ## N49°00'09" E008°23'33"
Mehr Informationen über die Mailingliste Talk-de