Ich denke, es ist an der Zeit, mein Projekt einmal zu releasen. Es handelt sich dabei um eine asynchrone Netzwerklibrary, welche unter Python 2.x (2.5 aufwärts, aber bei großem Interesse portiere ich sie gerne auch auf 2.4 zurück, dachte nur einmal, das sei die Arbeit nicht wirklich wert, und vor allem nicht die damit verbundene Verringerung der Lesbarkeit des Codes) und 3.x lauffähig ist. Das offizielle Zuhause der Library ist im Moment http://segfaulthunter.github.com/asynchia/, zu finden sind die Builds aber auch im pypi (also installierbar über easy_install oder pip). Ich würde mich sehr freuen, wenn jemand ein wenig mit der Library herumprobierte und mir etwaiges Feedback entweder hier oder durch den Issue-Tracker auf GitHub mitteilte.
An der ROADMAP kann man grob erkennen, was für die Zukunft der Library geplant ist.
In diesem Sinne einmal ein Danke im vorhinein an alle, die sich die Library mal ansehen oder damit herumprobieren.
asynchia — Netzwerklibrary für 2.x und 3.x
Ohloh | Mein Blog | Jabber: segfaulthunter@swissjabber.eu | asynchia – asynchrone Netzwerkbibliothek
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
Ich kenn sie ja schon aus'm IRC und muss sagen, wirklich gut. Ich hab zwar noch nicht viel damit gemacht, aber ich hab ja angekündigt, wenn asynchia released ist, dass ich dann eine kleine IRC-lib mit ihr schreibe, die wird dann auch bald kommen.
the more they change the more they stay the same
-
lunar
@name: Ich finde, dass die Dokumentation nicht nur im Bezug auf das Tutorial, sondern im Allgemeinen nicht gelungen ist.
Die API-Dokumentation bietet nur eine Liste aller verfügbaren Klassen ohne Struktur und Gliederung, und dient somit nur als Referenz. Sie ist nur brauchbar, wenn man die nötige Klasse kennt, und nur die Details ihrer Verwendung nachschlagen will. Um überhaupt herauszufinden, welche Klasse man benötigt, ist sie kaum geeignet. Das ist nun per se nicht schlimm, wenn der Rest der Dokumentation die Zusammenhänge detailliert erklären würde, allerdings beschränkt sich der Rest auf doch recht knappe Tutorien, in denen die grundlegenden Begriffe zwar knapp erklärt, aber nicht in Zusammenhang gestellt werden. Die recht kurze Beispielanwendung reicht dann nicht aus, um ein wirklich tiefgehendes Verständnis der Bibliothek zu vermitteln. Das gilt für alle drei Tutorien zu den verschiedenen Teilen der Bibliothek.
Soweit zum großen Zusammenhang, darüber hinaus gibt es noch Kleinigkeiten. Es fehlen Querverweise zwischen Tutorien und API-Dokumentation (e.g. warum ist "asynchia.maps.DefaultSocketMap" im ersten Tutorium kein Link auf die API-Dokumentation der Klasse?).
Die API-Dokumentation bzw. die Docstrings fast immer zu knapp, es fehlen oft genug wichtige Informationen. Manchmal sind Parameter nicht dokumentiert (e.g. "closing" und "autoflush" in der Klasse "FileExpr" oder "err" in "Transport.handle_connect_failed"), und wenn, dann sind sie nicht näher beschrieben (e.g. insbesondere hinsichtlich der erwarteten Typen). Gleiches gilt für die Rückgabewerte. Da zudem so gut wie nie Quelltextbeispiele zur Verwendung einer Klasse in den Docstrings vorkommen, sind die Docstrings und somit auch die gesamte API-Dokumentation reichlich schwer verständlich, und vor allem für mit der Thematik nicht vertraute Personen fast schon nutzlos. Die ab und zu auftretenden Rechtschreibfehler hinterlassen ebenfalls keinen guten Eindruck.
Außerdem enthält die API-Dokumentation viele nahezu undokumentierte Klassen (z.B. State), die den Eindruck von internen Klassen erwecken, was zur Frage führt, warum sie dann überhaupt in der Dokumentation auftauchen.
Zudem stellt sich zumindest mir die Frage, warum Du epydoc und nicht die autodoc-Erweiterung von Sphinx für die API-Dokumentation verwendet hast. Meine erste Vermutung wäre, dass epydoc schlicht einfacher war, was dann wiederum nahelegt, dass Du Dir bei der Dokumentation nicht viel Mühe gegeben hast, ein Eindruck, der vom Rest der Dokumentation bestätigt wird.
Über den Quelltext kann ich mir kein Urteil erlauben, da ich ihn nicht angesehen habe. Würde ich die Bibliothek für ein Projekt in Erwägung ziehen, wäre ich auch gar nicht so weit gekommen. Der erste Blick geht immer in die Dokumentation, und die hinterlässt – verzeih meine Offenheit – einen sehr schlechten Eindruck.
Ein erster Schritt zu ihrer Verbesserung wäre, alle Docstrings zu überarbeiten, und dabei darauf zu achten, dass die Funktionsweise des dokumentierten Objekts umfassend erklärt ist und alle Parameter sowie der Rückgabewert dokumentiert sind, auch hinsichtlich der Typen, die erwartet und zurückgegeben werden. Natürlich ist Python dynamisch, aber ganz ohne Informationen über Typen geht es eben nicht. Dann sollten wichtige Objekte im Docstring Quelltext-Beispiele zu ihrer Verwendung haben, am besten als Doctest, um die Korrektheit der Beispiele testen zu können.
Der nächste Schritt wäre der Verzicht auf epydoc, und die Verwendung der autodoc-Erweiterung. Mithilfe dieser Erweiterung kannst Du die API-Dokumentation in die Dokumentation integrieren, und so auch Querverweise hinzufügen. Zudem kannst Du die API-Dokumentation entsprechend der Struktur der Bibliothek gliedern, und interne Klassen ganz weglassen.
Zuguterletzt würde ich dann die Tutorien überarbeiten. Definitionen gehören in Referenzdokumente, nicht in Tutorien. Die Bedeutung einer Klasse oder eines Konzepts erklärt man in einem Tutorium, wenn sie das erste Mal auftaucht, nicht pauschal am Anfang. Auch am didaktischen Aufbau wäre zu arbeiten. Am Anfang des Tutoriums solltest Du das Szenario bzw. den Zweck der Anwendung umreißen. Anschließend sollte die Anwendung Schritt für Schritt mit entsprechenden Erklärungen aufgebaut werden, anstatt schlicht den gesamten Quelltext zu zeigen. Da kann die Anwendungen dann auch gerne etwas komplexer, dafür aber näher an der Realität sein.
Die API-Dokumentation bietet nur eine Liste aller verfügbaren Klassen ohne Struktur und Gliederung, und dient somit nur als Referenz. Sie ist nur brauchbar, wenn man die nötige Klasse kennt, und nur die Details ihrer Verwendung nachschlagen will. Um überhaupt herauszufinden, welche Klasse man benötigt, ist sie kaum geeignet. Das ist nun per se nicht schlimm, wenn der Rest der Dokumentation die Zusammenhänge detailliert erklären würde, allerdings beschränkt sich der Rest auf doch recht knappe Tutorien, in denen die grundlegenden Begriffe zwar knapp erklärt, aber nicht in Zusammenhang gestellt werden. Die recht kurze Beispielanwendung reicht dann nicht aus, um ein wirklich tiefgehendes Verständnis der Bibliothek zu vermitteln. Das gilt für alle drei Tutorien zu den verschiedenen Teilen der Bibliothek.
Soweit zum großen Zusammenhang, darüber hinaus gibt es noch Kleinigkeiten. Es fehlen Querverweise zwischen Tutorien und API-Dokumentation (e.g. warum ist "asynchia.maps.DefaultSocketMap" im ersten Tutorium kein Link auf die API-Dokumentation der Klasse?).
Die API-Dokumentation bzw. die Docstrings fast immer zu knapp, es fehlen oft genug wichtige Informationen. Manchmal sind Parameter nicht dokumentiert (e.g. "closing" und "autoflush" in der Klasse "FileExpr" oder "err" in "Transport.handle_connect_failed"), und wenn, dann sind sie nicht näher beschrieben (e.g. insbesondere hinsichtlich der erwarteten Typen). Gleiches gilt für die Rückgabewerte. Da zudem so gut wie nie Quelltextbeispiele zur Verwendung einer Klasse in den Docstrings vorkommen, sind die Docstrings und somit auch die gesamte API-Dokumentation reichlich schwer verständlich, und vor allem für mit der Thematik nicht vertraute Personen fast schon nutzlos. Die ab und zu auftretenden Rechtschreibfehler hinterlassen ebenfalls keinen guten Eindruck.
Außerdem enthält die API-Dokumentation viele nahezu undokumentierte Klassen (z.B. State), die den Eindruck von internen Klassen erwecken, was zur Frage führt, warum sie dann überhaupt in der Dokumentation auftauchen.
Zudem stellt sich zumindest mir die Frage, warum Du epydoc und nicht die autodoc-Erweiterung von Sphinx für die API-Dokumentation verwendet hast. Meine erste Vermutung wäre, dass epydoc schlicht einfacher war, was dann wiederum nahelegt, dass Du Dir bei der Dokumentation nicht viel Mühe gegeben hast, ein Eindruck, der vom Rest der Dokumentation bestätigt wird.
Über den Quelltext kann ich mir kein Urteil erlauben, da ich ihn nicht angesehen habe. Würde ich die Bibliothek für ein Projekt in Erwägung ziehen, wäre ich auch gar nicht so weit gekommen. Der erste Blick geht immer in die Dokumentation, und die hinterlässt – verzeih meine Offenheit – einen sehr schlechten Eindruck.
Ein erster Schritt zu ihrer Verbesserung wäre, alle Docstrings zu überarbeiten, und dabei darauf zu achten, dass die Funktionsweise des dokumentierten Objekts umfassend erklärt ist und alle Parameter sowie der Rückgabewert dokumentiert sind, auch hinsichtlich der Typen, die erwartet und zurückgegeben werden. Natürlich ist Python dynamisch, aber ganz ohne Informationen über Typen geht es eben nicht. Dann sollten wichtige Objekte im Docstring Quelltext-Beispiele zu ihrer Verwendung haben, am besten als Doctest, um die Korrektheit der Beispiele testen zu können.
Der nächste Schritt wäre der Verzicht auf epydoc, und die Verwendung der autodoc-Erweiterung. Mithilfe dieser Erweiterung kannst Du die API-Dokumentation in die Dokumentation integrieren, und so auch Querverweise hinzufügen. Zudem kannst Du die API-Dokumentation entsprechend der Struktur der Bibliothek gliedern, und interne Klassen ganz weglassen.
Zuguterletzt würde ich dann die Tutorien überarbeiten. Definitionen gehören in Referenzdokumente, nicht in Tutorien. Die Bedeutung einer Klasse oder eines Konzepts erklärt man in einem Tutorium, wenn sie das erste Mal auftaucht, nicht pauschal am Anfang. Auch am didaktischen Aufbau wäre zu arbeiten. Am Anfang des Tutoriums solltest Du das Szenario bzw. den Zweck der Anwendung umreißen. Anschließend sollte die Anwendung Schritt für Schritt mit entsprechenden Erklärungen aufgebaut werden, anstatt schlicht den gesamten Quelltext zu zeigen. Da kann die Anwendungen dann auch gerne etwas komplexer, dafür aber näher an der Realität sein.
Guten Tag.
Danke an alle, die sich die Zeit genommen haben, (teilweise recht ausführliche) Kommentare über meine Bibliothek (oder deren Dokumentation) zu verfassen. Dem ungeachtet ist dies nicht ganz die Kritik, die ich mir durch das Release erhofft hatte. Ich verweise nun einmal auf den ersten Satz der asynchia Dokumentation, der wie folgt lautet: „First of all, you are reminded that both asynchia and this documentation are in an alpha phase. This is the first asynchia release so bugs are to be expected.” asychia, als eine Own-Man-Show, hat sehr begrenze Ressourcen; deshalb ist es essentiell, Prioritäten zu setzen. Da dies das allererste Alpha-Release der Bibliothek ist, ist davon auszugehen, dass sich die API in nicht zu ferner Zukunft noch ändern wird, eventuell sogar relativ gravierend. Darin liegt auch das Problem, für das erste Release eine ausführliche — ergo aufwändige — Dokumentation zu verfassen: Diese Dokumentation wird für das nächste Release völlig ungeeignet, also veraltet und teilweise sogar falsch, sein. Die Ressourcen, die sonst in dieser bald veralteten Dokumentation in nicht allzulanger Zeit defacto verschwendet worden wären, habe ich lieber für Testen und das Implementieren neuer Features aufgebracht.
„Wieso dann das Release?”, möge sich nun mancher fragen. Für wichtigen Produktivcode ist die Bibliothek noch nicht reif, doch um einmal in dieses Stadium zu gelangen, ist es wichtig, dass sie von einem möglichst breiten Publikum zu Testzwecken angewandt wird (es ist mir unmöglich, sie auf sämtlichen wichtigen Plattformen zu testen, nichtsdestotrotz habe ich sie vor dem Release auf meinem Linux, in einer FreeBSD VM, auf einem Mac und einem Windows XP getestet). Und ich denke sehrwohl — wobei ich in diese Hinsicht wohl dadurch, dass ich die Library verfasst habe, nicht der objektivste Maßstab bin —, dass es möglich ist, mit der existierenden Dokumentation und ein wenig Eigenrecherche im Quellcode (der ja nun doch noch überschaubar ist), sich soweit mit der Bibliothek vertraut zu machen, um kleine Experimente damit anzustellen.
Ich bitte darum, mich nicht falsch zu verstehen: Ich nehme die Kritik ernst und versuche keineswegs, die Versäumnisse bezüglich der Dokumentation irgendwie herunterzuspielen; zudem werde ich versuchen, die Dokumentation im sinnvollen Rahmen zu überarbeiten (es ergibt keinen Sinn, bei frühen Releases mehr Zeit in die Dokumentation als in die eigentliche Library zu investieren). Es war mir nur ein Anliegen, mitzuteilen, dass die Dokumentation im Lichte des Alpha-Releases betrachtet werden sollte, und deshalb, wie schon im ersten Satz derselben angemerkt, unvollständig oder sogar fehlerhaft (was ich aber nicht hoffe, aber es kann natürlich sein, dass mir minimale Fehler entgangen sind) sein kann.
Zu guter Letzt möchte ich noch auf den Kritikpunkt, die API-Dokumentation nutze epydoc, eingehen. Es ist natürlich bedauerlich, wenn Cross-references o.ä. in einer Dokumentation fehlen. Andererseits sollte hier auch das Input-Output-Verhältnis betrachtet werden: Die API-Dokumentation vollautomatisch mit epydoc zu generieren ist sehr viel unaufwändiger, als diese mittels Sphinx-autodoc zu generieren, und das bei, meiner Meinung nach, verschmerzbaren Nachteilen. Ich möchte diesbezüglich nur einmal auf die CPython-Dokumentation zu kqueue hingewiesen haben, in welcher die Online-Dokumentation erheblich karger und unverständlicher ist, als jene, die man im Interpreter durch help aufrufen kann (also als die Docstrings) — etwas was durch verwenden von epydoc nicht passieren kann (wobei mir ein gerade anderes, peinliches Problem aufgefallen ist: dadurch, dass die Docs auf einem Linux-Rechner generiert wurden, scheint die KQueueSocketMap nicht in den API-Docs auf, was zwar eigentlich irrelevant, da sich diese für Endbenutzer genauso verhält, wie die anderen SocketMaps, aber trotzdem ungünstig ist).
Hoffentlich konnte ich hiermit ein wenig meine Gründe für die zugegeben etwas spärliche Dokumentation darlegen, und möchte abschließend noch sagen, dass Dokumentations- sowie Code-Patches natürlich äußerst erwünscht sind, und dass es für mich am angenehmsten ist, wenn etwaige Änderungen in einem Git-Repository getätigt werden, welches ich dann in meines mergen kann.
Danke an alle, die sich die Zeit genommen haben, (teilweise recht ausführliche) Kommentare über meine Bibliothek (oder deren Dokumentation) zu verfassen. Dem ungeachtet ist dies nicht ganz die Kritik, die ich mir durch das Release erhofft hatte. Ich verweise nun einmal auf den ersten Satz der asynchia Dokumentation, der wie folgt lautet: „First of all, you are reminded that both asynchia and this documentation are in an alpha phase. This is the first asynchia release so bugs are to be expected.” asychia, als eine Own-Man-Show, hat sehr begrenze Ressourcen; deshalb ist es essentiell, Prioritäten zu setzen. Da dies das allererste Alpha-Release der Bibliothek ist, ist davon auszugehen, dass sich die API in nicht zu ferner Zukunft noch ändern wird, eventuell sogar relativ gravierend. Darin liegt auch das Problem, für das erste Release eine ausführliche — ergo aufwändige — Dokumentation zu verfassen: Diese Dokumentation wird für das nächste Release völlig ungeeignet, also veraltet und teilweise sogar falsch, sein. Die Ressourcen, die sonst in dieser bald veralteten Dokumentation in nicht allzulanger Zeit defacto verschwendet worden wären, habe ich lieber für Testen und das Implementieren neuer Features aufgebracht.
„Wieso dann das Release?”, möge sich nun mancher fragen. Für wichtigen Produktivcode ist die Bibliothek noch nicht reif, doch um einmal in dieses Stadium zu gelangen, ist es wichtig, dass sie von einem möglichst breiten Publikum zu Testzwecken angewandt wird (es ist mir unmöglich, sie auf sämtlichen wichtigen Plattformen zu testen, nichtsdestotrotz habe ich sie vor dem Release auf meinem Linux, in einer FreeBSD VM, auf einem Mac und einem Windows XP getestet). Und ich denke sehrwohl — wobei ich in diese Hinsicht wohl dadurch, dass ich die Library verfasst habe, nicht der objektivste Maßstab bin —, dass es möglich ist, mit der existierenden Dokumentation und ein wenig Eigenrecherche im Quellcode (der ja nun doch noch überschaubar ist), sich soweit mit der Bibliothek vertraut zu machen, um kleine Experimente damit anzustellen.
Ich bitte darum, mich nicht falsch zu verstehen: Ich nehme die Kritik ernst und versuche keineswegs, die Versäumnisse bezüglich der Dokumentation irgendwie herunterzuspielen; zudem werde ich versuchen, die Dokumentation im sinnvollen Rahmen zu überarbeiten (es ergibt keinen Sinn, bei frühen Releases mehr Zeit in die Dokumentation als in die eigentliche Library zu investieren). Es war mir nur ein Anliegen, mitzuteilen, dass die Dokumentation im Lichte des Alpha-Releases betrachtet werden sollte, und deshalb, wie schon im ersten Satz derselben angemerkt, unvollständig oder sogar fehlerhaft (was ich aber nicht hoffe, aber es kann natürlich sein, dass mir minimale Fehler entgangen sind) sein kann.
Zu guter Letzt möchte ich noch auf den Kritikpunkt, die API-Dokumentation nutze epydoc, eingehen. Es ist natürlich bedauerlich, wenn Cross-references o.ä. in einer Dokumentation fehlen. Andererseits sollte hier auch das Input-Output-Verhältnis betrachtet werden: Die API-Dokumentation vollautomatisch mit epydoc zu generieren ist sehr viel unaufwändiger, als diese mittels Sphinx-autodoc zu generieren, und das bei, meiner Meinung nach, verschmerzbaren Nachteilen. Ich möchte diesbezüglich nur einmal auf die CPython-Dokumentation zu kqueue hingewiesen haben, in welcher die Online-Dokumentation erheblich karger und unverständlicher ist, als jene, die man im Interpreter durch help aufrufen kann (also als die Docstrings) — etwas was durch verwenden von epydoc nicht passieren kann (wobei mir ein gerade anderes, peinliches Problem aufgefallen ist: dadurch, dass die Docs auf einem Linux-Rechner generiert wurden, scheint die KQueueSocketMap nicht in den API-Docs auf, was zwar eigentlich irrelevant, da sich diese für Endbenutzer genauso verhält, wie die anderen SocketMaps, aber trotzdem ungünstig ist).
Hoffentlich konnte ich hiermit ein wenig meine Gründe für die zugegeben etwas spärliche Dokumentation darlegen, und möchte abschließend noch sagen, dass Dokumentations- sowie Code-Patches natürlich äußerst erwünscht sind, und dass es für mich am angenehmsten ist, wenn etwaige Änderungen in einem Git-Repository getätigt werden, welches ich dann in meines mergen kann.
Ohloh | Mein Blog | Jabber: segfaulthunter@swissjabber.eu | asynchia – asynchrone Netzwerkbibliothek
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
Hallo.
Sebastian
Und wie stellst du dir eine Verwendung ohne eine halbwegs vernünftige Dokumentation vor? Die Zeit, welche du durch das Nicht-Erstellen sparst, müssen dann potentielle Tester bei der Einarbeitung leisten. Da mag das Projekt noch so interessant sein, aber ich mache mir die Mühe dann einfach nicht. Und das geht vielen anderen sicher ähnlich.name hat geschrieben:„Wieso dann das Release?”, möge sich nun mancher fragen. Für wichtigen Produktivcode ist die Bibliothek noch nicht reif, doch um einmal in dieses Stadium zu gelangen, ist es wichtig, dass sie von einem möglichst breiten Publikum zu Testzwecken angewandt wird (es ist mir unmöglich, sie auf sämtlichen wichtigen Plattformen zu testen, nichtsdestotrotz habe ich sie vor dem Release auf meinem Linux, in einer FreeBSD VM, auf einem Mac und einem Windows XP getestet).
Sebastian
Das Leben ist wie ein Tennisball.
Ich sagte ja bereits, dass ich denke, dass die Dokumentation zwar nicht optimal, aber eben doch brauchbar ist, zudem ist ja eine gewisse Ähnlichkeit zu asyncore nicht zu leugnen, was die Einarbeitung noch etwas vereinfacht, sofern man dieses schon benutzt hat. Die grundlegenden Konzepte werden in den Tutorials — ob jetzt didaktisch gut oder nicht sei an diesem Punkt einmal dahingestellt — ausreichend behandelt, um etwas mit der Library anfangen zu können (wobei diese ja nicht wirklich komplex sind). Wenn sie wirklich so unbrauchbar sind, wie es aus euren Posts zu deuten ist, unterliege ich diesbezüglich wohl einer Fehleinschätzung.EyDu hat geschrieben:Hallo.
Und wie stellst du dir eine Verwendung ohne eine halbwegs vernünftige Dokumentation vor? Die Zeit, welche du durch das Nicht-Erstellen sparst, müssen dann potentielle Tester bei der Einarbeitung leisten. Da mag das Projekt noch so interessant sein, aber ich mache mir die Mühe dann einfach nicht. Und das geht vielen anderen sicher ähnlich.name hat geschrieben:„Wieso dann das Release?”, möge sich nun mancher fragen. Für wichtigen Produktivcode ist die Bibliothek noch nicht reif, doch um einmal in dieses Stadium zu gelangen, ist es wichtig, dass sie von einem möglichst breiten Publikum zu Testzwecken angewandt wird (es ist mir unmöglich, sie auf sämtlichen wichtigen Plattformen zu testen, nichtsdestotrotz habe ich sie vor dem Release auf meinem Linux, in einer FreeBSD VM, auf einem Mac und einem Windows XP getestet).
Sebastian
Ohloh | Mein Blog | Jabber: segfaulthunter@swissjabber.eu | asynchia – asynchrone Netzwerkbibliothek
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
-
lunar
@name: Wir haben offenbar fundamental verschiedene Ansichten über die Wichtigkeit von Dokumentation, Deine Aussagen sehe ich kritisch.
Ich persönlich halte Dokumentation für wichtig, wichtiger noch als den Quelltext selbst, und zwar unabhängig vom Entwicklungsstand des Projekts. Gute Dokumentation ist für mich ein Zeichen hoher Qualität und eines qualitätsbewussten Entwicklerteams, mangelhafte Dokumentation dagegen eher Zeichen dafür, dass den Entwicklern die Qualität nicht wichtig ist. Deine Aussagen lassen mich daran zweifeln, dass Dokumentation für Dich jemals den in meinen Augen nötigen Stellenwert haben wird, auch wenn das Projekt seine Alpha-Phase hinter sich lässt.
Allerdings kann ich Dir natürlich nicht vorschreiben, wie Du Dein Projekt zu führen hast, und Du musst Dich auch nicht rechtfertigen vor mir, denn nachvollziehen kann ich Deine Einstellung eh nicht.
Ich persönlich halte Dokumentation für wichtig, wichtiger noch als den Quelltext selbst, und zwar unabhängig vom Entwicklungsstand des Projekts. Gute Dokumentation ist für mich ein Zeichen hoher Qualität und eines qualitätsbewussten Entwicklerteams, mangelhafte Dokumentation dagegen eher Zeichen dafür, dass den Entwicklern die Qualität nicht wichtig ist. Deine Aussagen lassen mich daran zweifeln, dass Dokumentation für Dich jemals den in meinen Augen nötigen Stellenwert haben wird, auch wenn das Projekt seine Alpha-Phase hinter sich lässt.
Allerdings kann ich Dir natürlich nicht vorschreiben, wie Du Dein Projekt zu führen hast, und Du musst Dich auch nicht rechtfertigen vor mir, denn nachvollziehen kann ich Deine Einstellung eh nicht.
Ich bin mir bewusst, dass Dokumentation wichtig ist (dass sie nun wichtiger als der echte Code sei, würde ich jedoch nicht unterschreiben). Ich denke nur nicht, dass es sinnvoll ist, in solch einem frühen Stadium aufwändige didaktisch wertvolle Dokumentation zu erstellen, die dann eh sofort wieder veraltet ist. Weiters denke ich nicht, dass von der Dokumentationsqualität auf die Codequalität geschlossen werden kann.lunar hat geschrieben:@name: Wir haben offenbar fundamental verschiedene Ansichten über die Wichtigkeit von Dokumentation, Deine Aussagen sehe ich kritisch.
Ich persönlich halte Dokumentation für wichtig, wichtiger noch als den Quelltext selbst, und zwar unabhängig vom Entwicklungsstand des Projekts. Gute Dokumentation ist für mich ein Zeichen hoher Qualität und eines qualitätsbewussten Entwicklerteams, mangelhafte Dokumentation dagegen eher Zeichen dafür, dass den Entwicklern die Qualität nicht wichtig ist. Deine Aussagen lassen mich daran zweifeln, dass Dokumentation für Dich jemals den in meinen Augen nötigen Stellenwert haben wird, auch wenn das Projekt seine Alpha-Phase hinter sich lässt.
Allerdings kann ich Dir natürlich nicht vorschreiben, wie Du Dein Projekt zu führen hast, und Du musst Dich auch nicht rechtfertigen vor mir, denn nachvollziehen kann ich Deine Einstellung eh nicht.
Ohloh | Mein Blog | Jabber: segfaulthunter@swissjabber.eu | asynchia – asynchrone Netzwerkbibliothek
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
-
lunar
@name: Mir müssen das nicht diskutieren. Ich glaube, unsere Standpunkte sind deutlich geworden, und es wird wohl keiner von uns den des anderen nachvollziehen können.
Ich möchte nur noch anmerken, dass ich keinesfalls von der Qualität der Dokumentation auf die des Quelltexts geschlossen habe. Man kann das zwar, wenn man möchte, aber das wäre unfair, da es sich ja letztlich um verschiedene Dinge handelt. Die Qualität der Dokumentation ist allerdings ein Aspekt der Qualität des gesamten Projekts, sie zu vernachlässigen bedeutet, dass ein Teil des Projekts eben nicht von hoher Qualität ist. Angesichts der Tatsache, dass es erfahrungsgemäß sehr schwierig ist, einmal erlittenen Qualitätsverlust wieder wettzumachen, finde ich das bedenklich. Nicht mehr und nicht weniger ...
Ich möchte nur noch anmerken, dass ich keinesfalls von der Qualität der Dokumentation auf die des Quelltexts geschlossen habe. Man kann das zwar, wenn man möchte, aber das wäre unfair, da es sich ja letztlich um verschiedene Dinge handelt. Die Qualität der Dokumentation ist allerdings ein Aspekt der Qualität des gesamten Projekts, sie zu vernachlässigen bedeutet, dass ein Teil des Projekts eben nicht von hoher Qualität ist. Angesichts der Tatsache, dass es erfahrungsgemäß sehr schwierig ist, einmal erlittenen Qualitätsverlust wieder wettzumachen, finde ich das bedenklich. Nicht mehr und nicht weniger ...
Bump, 0.1.1 wurde mit folgenden Änderungen gerade veröffentlicht: http://github.com/segfaulthunter/asynch ... /CHANGELOG. Die Docs werden alsbald es mir möglich ist upgedated, nur war das alte Release fundamental kaputt, sodass es notwendig ist, ein neues zu machen, was, da es keinen Kompatibilitätsbruch gibt, eigtl. kein Problem ist. Zudem haben die alten Docs immer noch ihre Richtigkeit, weil es neben den kritischen Bugfixes lediglich einige neue Komponenten gibt, die in den Docs genannte inperformantere aber weiterhin funktionstüchtige Methoden ersetzen.
Ohloh | Mein Blog | Jabber: segfaulthunter@swissjabber.eu | asynchia – asynchrone Netzwerkbibliothek
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.
In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.