Ähnlich wie bei Wie können Open Source-Projekte erfolgreich sein, ohne Dokumentation über Design oder Architektur? Frage, ich bin gespannt: Warum fehlen so viele Bibliotheken in der Endbenutzerdokumentation?
Meiner Ansicht nach ist dies:
- Die meisten sind sich einig, dass das Lesen von Quellcode schwieriger ist als das Schreiben von Quellcode.
- Ohne Dokumentation muss der Quellcode der Bibliothek gelesen werden, um diese Bibliothek nutzen zu können.
- Daher ist die Verwendung der undokumentierten Bibliothek mehr Arbeit als nur die Neuerstellung der Bibliothek von Grund auf.
- Wenn Sie also möchten, dass Ihre Bibliothek von Personen verwendet wird, sollten Sie verdammt noch mal sicherstellen, dass sie dokumentiert ist.
Ich weiß, dass viele Entwickler nicht gerne Dokumente schreiben, und ich bin mir sicher, dass dies eine mühsame Arbeit sein kann. Aber es ist eine wesentliche Arbeit. Ich würde sogar sagen, dass es wichtiger ist, dass eine Bibliothek eine gute Dokumentation hat als die beste Programmierschnittstelle der Welt. (Die Leute benutzen die ganze Zeit beschissene Bibliotheken; nur wenige benutzen undokumentierte Bibliotheken)
Oh, beachte, wenn ich Dokumentation sage, meine ich echte Dokumentation. Nicht Sandcastle / Javadoc / Doxygen Boilerplate.
quelle
Antworten:
Ich denke, Sie haben meistens Ihre eigene Frage beantwortet: In den meisten Fällen kümmern sich die Entwickler einfach nicht darum. Das Problem tritt besonders häufig bei Freiwilligenprojekten auf.
Ich denke jedoch, dass es ein weiteres großes Problem gibt: In vielen Fällen haben Entwickler kein Gesamtmodell für die Funktionsweise ihrer Bibliothek entwickelt (oder haben nur Schwierigkeiten, dieses Modell klar zu formulieren). Leider ist es oft der wichtigste Teil der Dokumentation, dieses Modell zu artikulieren und festzustellen, wie die Teile der Software zusammenpassen.
In einem typischen Fall hat das Geschriebene einen Überblick auf sehr hoher Ebene ("Dies ist eine Bibliothek, um coole Sachen zu machen!") Und dann eine Beschreibung auf sehr niedriger Ebene (Typ und Beschreibung jedes Parameters, der an jede Funktion übergeben werden soll). Leider gibt es selten eine Zwischenstufe in der allgemeinen Theorie, wie die Dinge funktionieren sollen, wie die Teile zusammenpassen usw. Ein Großteil davon geht auf die Tatsache zurück, dass Entwickler oft nicht versucht haben, sie zu formen, zu rationalisieren oder zu verstehen Code auf dieser bestimmten Detailebene. Zumindest in einigen Fällen, die ich gesehen habe, fanden es Entwickler, die aufgefordert wurden, Dokumentation auf dieser Ebene zu schreiben, ziemlich problematisch - bis zu dem Punkt, dass viele den Code neu schreiben wollten, damit er organisierter und einfacher auf dieser Ebene zu erklären wäre Detail.
Auf dieser Abstraktionsebene gut zu schreiben ist oft schwierig - und wenn der Entwickler auf dieser Abstraktionsebene nicht wirklich darüber nachgedacht hat , findet er den Code oft etwas peinlich und möchte ihn möglicherweise umschreiben, bevor er zufrieden ist darüber, es überhaupt freizugeben.
quelle
Ich denke, manchmal liegt es daran, dass der Entwickler so in den Code verwickelt ist, dass es für ihn / sie "offensichtlich" ist, wie es funktioniert, und dass sie nicht sehen können, warum es für andere nicht offensichtlich ist. In ähnlicher Weise sagen viele Produktwebsites, wie wunderbar ihr Produkt ist, aber sagen Sie nicht, was es tatsächlich tut!
quelle
Sie haben selbst auf die Antwort hingewiesen:
Als Programmierer schreiben wir gerne Code, aber nur sehr wenige von uns schreiben gerne Dokumentation.
Jeder gute Programmierer kennt den Wert einer guten Dokumentation, aber es braucht auch eine ganze Menge Zeit, um es richtig zu machen. Da es keinen Spaß macht und lange dauert, wird es in den Stapel "später erledigen" gelegt, damit es nie auf ein zufriedenstellendes Niveau gebracht wird.
Nebenbei bemerkt, es ist für einen Programmierer auch sehr schwierig, Dokumentationen über sein eigenes Produkt zu schreiben. Da sie das System so gut kennen, sind ihnen bestimmte Dinge klar. Diese Teile werden oft nie erwähnt, obwohl sie für den Verbraucher nicht offensichtlich sind.
quelle
Dokumentation zu schreiben ist eine Fähigkeit. Wie alle Fähigkeiten braucht es Übung. Die Zeit und der Aufwand, die wir für das Schreiben von Code aufwenden, zahlen sich sofort aus. Wir können die neue Funktion, den behobenen Fehler und die verbesserte Geschwindigkeit sehen. Das Schreiben von Unterlagen hat eine verzögerte Auszahlung. Es hilft auf lange Sicht, wenn neue Leute an dem Code arbeiten müssen oder wenn wir erst in Monaten oder Jahren wieder an dem Code arbeiten. Es ist nur natürlich, dass wir uns kurzfristig konzentrieren.
Meiner Meinung nach ist die Fähigkeit, gute Dokumentationen zu schreiben, eines der Hauptmerkmale, das große Programmierer von mittelmäßigen Programmierern unterscheidet.
quelle
Die Person, die am besten zum Verfassen von Dokumenten qualifiziert ist, ist auch die Person, die am wenigsten dazu motiviert ist:
er (oder sie) ist:
Ich kann mir niemanden vorstellen, bei dem es weniger wahrscheinlich ist, dass er sagt: "Hmm, ich sollte wirklich ein paar Stunden damit verbringen, eine richtige Dokumentation dafür zu schreiben." Warum sollte er?
Und natürlich hilft es wahrscheinlich nicht, dass es diese urbane Legende gibt, dass automatisch generierte Kommentare im Sauerstoffstil alles sind, was Sie für die Dokumentation benötigen.
Selbst in den seltenen Fällen, in denen ein Entwickler tatsächlich bereit ist , Dokumentation zu schreiben, ist es eine 50/50-Chance, dass der Entwickler von diesem Kult in die Gehirnwäsche getrieben wurde, zu denken, dass nur ein paar solche Kommentare ausgefüllt werden müssen, die Ihnen Edelsteine erzählen dass "die Funktion
Foo getFoo()ein Objekt vom Typ Foo zurückgibt und es verwendet wird, um das Foo-Objekt zu erhalten".quelle
Ich weiß, wie der Code funktioniert. Warum sollte ich Zeit damit verbringen, meinen Code zu dokumentieren? Außerdem muss dieses Projekt bis Freitag fertig sein und ich werde es kaum so machen, wie es ist ...
quelle