[Talk-de] Code im Wiki dokumentieren

[Frederik Ramm]

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"