http://withoutane.com/rants/2008/09/you ... tion-sucks
Das musste ich leider auch feststellen.
Hat jemand eine Erklärung dafür, weshalb die Dokumentation bei Python-Projekten so oft so extrem beschissen ist? Sogar bei manchen Modulen in der Standard Library ist die Dokumentation beschissen.
"Your Documentation Sucks"
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum. Letztendlich läuft es darauf hinaus, dass die Programmierer eben lieber Programmieren als Dokumentieren (und in der Regel auch keine guten Buchschreiber sind). Aber ich sehe jetzt an den Dokumenten nicht, warum du sie schlecht findest. Ich hatte keine Probleme, einfache Twisted-Services zu schreiben. Problematisch ist eher Twisted Words, wo die unvollständige API-Dokumentation so ziemlich alles ist was man hat. Roundup aufzusetzen war mit der Dokumentation auch kein Problem. PyPy ist eigentlich nicht für User gedacht, daher ist die Dokumentation verzeihlich. EE habe ich mal angetestet, bin aber nicht weit gekommen. Ob es die Schuld der Dokumentation ist? Keine Ahnung.epsilon hat geschrieben:http://withoutane.com/rants/2008/09/you ... tion-sucks
Das musste ich leider auch feststellen.
Hat jemand eine Erklärung dafür, weshalb die Dokumentation bei Python-Projekten so oft so extrem beschissen ist?
Andererseits finde ich die Genshi-Dokumentation nicht so toll, wie er schreibt. Es fehlt einfach ein Tutorial wie man was macht. Da finde ich die Jinja-Dokumentation wesenlich besser, Teils auch weil Jinja einfacher zu verstehen ist, teils aber weil die Dokumentation ziemlich gut ist. Die Werkzeug-Dokumentation ist auch nicht übel.
Wer nutzt denn heutzutage noch Hotshot? Ich hatte mit der Profiler-Dokumentation kaum Probleme, aber wenn du da Verbesserungsvorschläge hast, dann immer her damit.epsilon hat geschrieben:Sogar bei manchen Modulen in der Standard Library ist die Dokumentation beschissen.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
- veers
- User
- Beiträge: 1219
- Registriert: Mittwoch 28. Februar 2007, 20:01
- Wohnort: Zürich (CH)
- Kontaktdaten:
Ist das wirklich ein Python spezifisches Problem? Ist doch fast überall so. Ich denke die Dokumentation von vielen Opensource Projekten ist so schlecht weil sie für den Eigengebrauch geschrieben wurden. Der Entwickler braucht keine Benutzer Dokumentation um seinen eigenen Code zu verwenden, und Dokumentation zu schreiben ist imho auch nicht gerade das spannendste
Bei proprietärer Software ist es oft auch nicht anders - nur da ist read the fucking source keine Option.
Bei proprietärer Software ist es oft auch nicht anders - nur da ist read the fucking source keine Option.
[url=http://29a.ch/]My Website - 29a.ch[/url]
"If privacy is outlawed, only outlaws will have privacy." - Phil Zimmermann
"If privacy is outlawed, only outlaws will have privacy." - Phil Zimmermann
@epsilon: Bei der `hotshot`-Dokumentation ist gleich am Anfang ein Hinweis, dass für den allgemeinen Gebrauch `cProfile` empfohlen wird, `hotshot` nicht gepflegt wird, und in Zukunft aus der Standardbibliothek verschwinden könnte. Ab da braucht's IMHO nicht mehr Dokumentation. Im Gegenteil, gute Dokumentation könnte Leute ermutigen das Modul *trotzdem* zu verwenden.
@Leonidas: Bei PyPy würde ich allerdings gute Dokumentation erwarten. Da wurden EU-Fördermittel verwendet, und der EU-Bürger sollte in die Lage versetzt werden auszuprobieren was die mit seinen Steuergeldern gemacht haben.
@Leonidas: Bei PyPy würde ich allerdings gute Dokumentation erwarten. Da wurden EU-Fördermittel verwendet, und der EU-Bürger sollte in die Lage versetzt werden auszuprobieren was die mit seinen Steuergeldern gemacht haben.
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
Du kannst ja die Papers lesen. Schließlich waren es Forschungsgelder die nun eben in die Forschung gesetzt worden sind.BlackJack hat geschrieben:@Leonidas: Bei PyPy würde ich allerdings gute Dokumentation erwarten. Da wurden EU-Fördermittel verwendet, und der EU-Bürger sollte in die Lage versetzt werden auszuprobieren was die mit seinen Steuergeldern gemacht haben.
Es hängt ja auch ab was man erwartet. Wenn man etwas über die Implementatoren-Sicht einer Programmiersprache lernen will dann ist die Dokumentation, hmm, akzeptabel. Wenn man allerinds einen Python-Interpretr in Python laufen lassen will, als ersatz für CPython dann nicht. Letzteres ist aber eigentlich eher als Nebenprodukt von PyPy zu sehen; das ist auch der Unterschied zwischen PyPy und Rubinius.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
Für von mir selbst geschriebenen Code brauche ich auch keine Dokumentation (wobei ich bei komplexeren Funktionen mindestens aufschreibe, was für Parameter übergeben werden und was am Ende raus kommt. Schon alleine, weil ich zu faul bin die Datei rauszukrammen, wenn ich nach ein paar Monaten die Funktion wieder verwenden möchte).Leonidas hat geschrieben:Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum.
Das kann ich natürlich nachvollziehen. Allerdings sollte es doch möglich sein, "wenigstens" eine halbwegs vollständige API-Dokumentation zu schreiben. Von gut formulierten und verständlichen Tutorials usw. rede ich ja gar nicht. Ich finde es nur nicht besonders schön, wenn ich erst den Code lesen und verstehen muss, wenn ich ein bestimmtes Modul verwenden möchte.Leonidas hat geschrieben:Letztendlich läuft es darauf hinaus, dass die Programmierer eben lieber Programmieren als Dokumentieren (und in der Regel auch keine guten Buchschreiber sind).
Von den dort genannten Projekten habe ich bisher nur Twisted verwendet; ich (und ich glaube der Typ ebenfalls) finde eher, dass die Dokumentation allgemein oft schlecht ist.Leonidas hat geschrieben:Aber ich sehe jetzt an den Dokumenten nicht, warum du sie schlecht findest.
Nehmen wir mal twiested.web.client als Beispiel. Der Download einer Webseite ist ja noch ganz leicht. In der API-Dokumentation von getPage sehe ich ja, dass ich als ersten Parameter eine URL übergeben kann. Was ist aber, wenn ich mich jetzt irgendwo einloggen möchte, geht das überhaupt? Bei getPage steht nur
.See HTTPClientFactory to see what extra args can be passed.
Wenn ich mir jetzt __init__ von HTTPClientFactory ansehe, sehe ich das hier:
Jetzt sehe ich wenigsten schon einmal, dass es zu gehen scheint. Was ich allerdings scheinbar erraten soll ist, was postdata, cookies und headers sein soll (string, list, dict?). Wenn ich in den Quelltext von __init__ schaue, finde ich dann sogar das heraus.def __init__(self, url, method='GET', postdata=None, headers=None, agent='Twisted PageGetter', timeout=0, cookies=None, followRedirect=1): (source)
overridden in twisted.web.client.HTTPDownloader
Undocumented
Das gleich gilt, wenn ich wissen möchte, ob der Client https versteht. Im Endeffekt muss ich wieder in den Quelltext schauen.
Warum kann der Autor nicht zu getPage schreiben, was für Parameter man übergeben kann, und ob https, cookies usw. unterstützt werden? Mehr als 5 Minuten hätte das doch sicherlich nicht gedauert. So muss jeder, der die Funktion benutzen möchte bei jeder Sache den Quellcode ansehen.
Wobei die Dokumentation bei twisted nur teilweise schlecht ist. Das Konzept usw. ist imho gut erklärt (und umfangreich).
Mir ist es auf jeden Fall bisher nur bei Python (so stark) aufgefallen.veers hat geschrieben:Ist das wirklich ein Python spezifisches Problem? Ist doch fast überall so.
Zum Bespiel steht bei den Methoden meiner Meinung zu wenig und die Parameter sind teilweise schlecht oder gar nicht erklärt (was kann ich zum Beispiel mit addinfo machen? Ich wüsste nicht, wofür ich das verwenden sollte. Oder bei runctx, was kann "globals" und "locals" sein, ein dict?). Im Endeffekt war ich in der Lage hotshot zu verwenden, ich finde die Dokumentation aber trotzdem nicht optimal.Leonidas hat geschrieben:Ich hatte mit der Profiler-Dokumentation kaum Probleme, aber wenn du da Verbesserungsvorschläge hast, dann immer her damit.
Leonidas hat geschrieben:Wer nutzt denn heutzutage noch Hotshot?
Das zählt aber imho beides nicht als Argument. Schließlich ist die Dokumentation seit Python 2.2 so, oder glaubt ihr die Dokumentation ist mit der Zeit weniger gewordenBlackJack hat geschrieben:@epsilon: Bei der `hotshot`-Dokumentation ist gleich am Anfang ein Hinweis, dass für den allgemeinen Gebrauch `cProfile` empfohlen wird, `hotshot` nicht gepflegt wird, und in Zukunft aus der Standardbibliothek verschwinden könnte. Ab da braucht's IMHO nicht mehr Dokumentation. Im Gegenteil, gute Dokumentation könnte Leute ermutigen das Modul *trotzdem* zu verwenden.
Und dann ist hotshot (soweit ich weiß) der einzige Profiler, der auf Zeilenebene statt auf Funktionsebene profilen kann. Ich bin also "gezwungen" hotshot zu verwenden, wenn ich genaue Daten haben will.
Dazu muss ich jetzt noch sagen, dass es sicher konstruktivere Wege gegeben hätte, als das was der Typ oder ich im ersten Post geschrieben haben ("so oft so extrem beschissen" kommt mir gerade etwas "hart" formuliert vor). Aber manchmal ist die Doku wirklich alles andere als gut bzw. vorhanden (siehe twisted.web.client)
Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?epsilon hat geschrieben:Für von mir selbst geschriebenen Code brauche ich auch keine Dokumentation (wobei ich bei komplexeren Funktionen mindestens aufschreibe, was für Parameter übergeben werden und was am Ende raus kommt. Schon alleine, weil ich zu faul bin die Datei rauszukrammen, wenn ich nach ein paar Monaten die Funktion wieder verwenden möchte).Leonidas hat geschrieben:Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum.
Btw, Twisted ist freie Software, wieso also investierst du diese "fünf" Minuten nicht selbst? Ach ja, du schreibst ja selbst auch keine Doku ... ob die fünf Minuten, die du in diesen Thread investierst hast, allerdings zielführender waren, sei mal dahin gestellt.
Im Übrigen finde ich auch die Paste-Dokumentation nicht schlecht ...
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
API-Docs sind fürn A*. Django gilt als gut Dokumentiert und hat dennoch keine (offizielle), weil die Doku zwar sagt, was in man wie aufrufen kann, aber nicht wie man irgendetwas erreicht. Beispiel python-openid. Es hat eine API-Doku, aber die API selbst ist dermaßen dumm, dass man sowieso die Quelltext-Beispiele entziffern muss, um herauszubekommen, dass eine Response und eine WebResponse zwei verschiedene Dinge sind und das eine in das andere konvertiert werden muss.epsilon hat geschrieben:Das kann ich natürlich nachvollziehen. Allerdings sollte es doch möglich sein, "wenigstens" eine halbwegs vollständige API-Dokumentation zu schreiben.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
Mit dem Absatz meinte ich Code, den nur ich selbst verwende (alles andere würde ja wohl keinen Sinn machen).lunar hat geschrieben:Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?
Das habe ich zwar nie behauptet, aber ok...lunar hat geschrieben:Ach ja, du schreibst ja selbst auch keine Doku ...
Deswegen wohl auch der letzte Absatzlunar hat geschrieben:Btw, Twisted ist freie Software, wieso also investierst du diese "fünf" Minuten nicht selbst? [...] ob die fünf Minuten, die du in diesen Thread investierst hast, allerdings zielführender waren, sei mal dahin gestellt.
Wie lang soll es denn sonst für den Autor dauern, für seine eigene Funktion und die 9 möglichen Parameter eine Beschreibung zu schreiben?lunar hat geschrieben:[...] "fünf" Minuten [...]
werd' ich machen...lunar hat geschrieben:[...] wieso also investierst du diese "fünf" Minuten nicht selbst?
Das las sich anders ...epsilon hat geschrieben:Mit dem Absatz meinte ich Code, den nur ich selbst verwende (alles andere würde ja wohl keinen Sinn machen).lunar hat geschrieben:Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?
Für von mir selbst geschriebenen Code brauche ich auch keine Dokumentation
Wie lange man dafür braucht, ist nicht der Punkt. Das die, die sich beschweren, die bemängelte Doku offenbar nicht selbst schreiben wollen, stört mich. Das bezieht sich jetzt auch weniger auf die als auf den Autor des Blogpostings.Wie lang soll es denn sonst für den Autor dauern, für seine eigene Funktion und die 9 möglichen Parameter eine Beschreibung zu schreiben?lunar hat geschrieben:[...] "fünf" Minuten [...]
Dieses: "Na dann schreib Du doch die Doku statt Dich zu beschweren." ist ein blödes Argument. Ist jetzt nicht Python, aber mir fehlt zu Io Dokumentation zu einigen Sachen. Ich traue mir aber nicht zu die zu schreiben, weil ich die Zusammenhänge eben teilweise nicht durchschaue und sich schon zweimal herausgestellt hat, das meine Erklärungen zwar das Verhalten das *ich* beobachten konnte ausreichend beschrieben, aber falsch waren. Jede etwas komplexere API sollte besser von Leuten dokumentiert werden, die sich damit auskennen, und nicht von Leuten die mal eben den Teil aus ihrer Sicht in fünf Minuten dokumentieren, den sie gerade selbst benötigt haben. Denn falsche und irreführende Dokumentation ist noch schlimmer als gar keine.
Also wenn sich jemand so sehr mit einem Paket beschäftigt, dass er – um eine Methode zu verstehen – auch die Quellen liest, gehe ich schon davon aus, dass er genügend Wissen angesammelt hat, um dazu Dokumentation zu verfassen. Im Übrigen übernimmt der Maintainer eingeschickte Dokumentationspatches ja in der Regel auch nicht einfach so, sondern liest sie gegen. Insofern kann selbst ein unvollständiger oder fehlerhafter Dokumentationspatch dem Maintainer als Startpunkt dienen.BlackJack hat geschrieben:Dieses: "Na dann schreib Du doch die Doku statt Dich zu beschweren." ist ein blödes Argument. Ist jetzt nicht Python, aber mir fehlt zu Io Dokumentation zu einigen Sachen. Ich traue mir aber nicht zu die zu schreiben, weil ich die Zusammenhänge eben teilweise nicht durchschaue