"Your Documentation Sucks"

Gute Links und Tutorials könnt ihr hier posten.
epsilon
User
Beiträge: 71
Registriert: Freitag 20. Juni 2008, 19:48

"Your Documentation Sucks"

Beitragvon epsilon » Montag 15. September 2008, 10:07

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.
Benutzeravatar
Leonidas
Administrator
Beiträge: 16023
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Re: "Your Documentation Sucks"

Beitragvon Leonidas » Montag 15. September 2008, 10:42

epsilon hat geschrieben:http://withoutane.com/rants/2008/09/your-documentation-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?

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.

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.

epsilon hat geschrieben:Sogar bei manchen Modulen in der Standard Library ist die Dokumentation beschissen.

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.
My god, it's full of CARs! | Leonidasvoice vs Modvoice
Benutzeravatar
veers
User
Beiträge: 1219
Registriert: Mittwoch 28. Februar 2007, 20:01
Wohnort: Zürich (CH)
Kontaktdaten:

Beitragvon veers » Montag 15. September 2008, 10:45

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.
My Website - 29a.ch
"If privacy is outlawed, only outlaws will have privacy." - Phil Zimmermann
BlackJack

Beitragvon BlackJack » Montag 15. September 2008, 14:12

@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. :-)
Benutzeravatar
Leonidas
Administrator
Beiträge: 16023
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Beitragvon Leonidas » Montag 15. September 2008, 14:37

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. :-)

Du kannst ja die Papers lesen. Schließlich waren es Forschungsgelder die nun eben in die Forschung gesetzt worden sind.

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 Modvoice
epsilon
User
Beiträge: 71
Registriert: Freitag 20. Juni 2008, 19:48

Beitragvon epsilon » Dienstag 16. September 2008, 12:57

Leonidas hat geschrieben:Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum.


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:Letztendlich läuft es darauf hinaus, dass die Programmierer eben lieber Programmieren als Dokumentieren (und in der Regel auch keine guten Buchschreiber sind).


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:Aber ich sehe jetzt an den Dokumenten nicht, warum du sie schlecht findest.


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.

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:

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


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.

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).

veers hat geschrieben:Ist das wirklich ein Python spezifisches Problem? Ist doch fast überall so.


Mir ist es auf jeden Fall bisher nur bei Python (so stark) aufgefallen.

Leonidas hat geschrieben:Ich hatte mit der Profiler-Dokumentation kaum Probleme, aber wenn du da Verbesserungsvorschläge hast, dann immer her damit.


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:Wer nutzt denn heutzutage noch Hotshot?

BlackJack 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.


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 geworden ;)


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)
lunar

Beitragvon lunar » Dienstag 16. September 2008, 17:12

epsilon hat geschrieben:
Leonidas hat geschrieben:Dann zeig mal deine Dokumentation. Ist sie nicht vorhanden, dann solltest du dich selbst fragen warum.


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).

Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?

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 ...
Benutzeravatar
Leonidas
Administrator
Beiträge: 16023
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Beitragvon Leonidas » Dienstag 16. September 2008, 18:34

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.

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.
My god, it's full of CARs! | Leonidasvoice vs Modvoice
epsilon
User
Beiträge: 71
Registriert: Freitag 20. Juni 2008, 19:48

Beitragvon epsilon » Dienstag 16. September 2008, 18:37

lunar hat geschrieben:Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?

Mit dem Absatz meinte ich Code, den nur ich selbst verwende (alles andere würde ja wohl keinen Sinn machen).

lunar hat geschrieben:Ach ja, du schreibst ja selbst auch keine Doku ...

Das habe ich zwar nie behauptet, aber ok...

lunar 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.

Deswegen wohl auch der letzte Absatz

lunar hat geschrieben:[...] "fünf" Minuten [...]

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:[...] wieso also investierst du diese "fünf" Minuten nicht selbst?

werd' ich machen...
lunar

Beitragvon lunar » Dienstag 16. September 2008, 19:06

epsilon hat geschrieben:
lunar hat geschrieben:Warum fragst du, wenn du die Antwort auf die Frage nach den Gründen schlechter Dokumentation doch am eigenen Beispiel zeigst?

Mit dem Absatz meinte ich Code, den nur ich selbst verwende (alles andere würde ja wohl keinen Sinn machen).

Das las sich anders ...
Für von mir selbst geschriebenen Code brauche ich auch keine Dokumentation


lunar hat geschrieben:[...] "fünf" Minuten [...]

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?

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.
BlackJack

Beitragvon BlackJack » Dienstag 16. September 2008, 19:57

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.
lunar

Beitragvon lunar » Dienstag 16. September 2008, 20:06

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

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.

Wer ist online?

Mitglieder in diesem Forum: 0 Mitglieder