Was ist mit der Abneigung gegen Dokumentation in der Branche?

47

Es scheint eine Abneigung gegen das Schreiben der grundlegendsten Dokumentation zu geben. Unsere Projekt-READMEs sind relativ einfach. Es gibt nicht einmal aktualisierte Listen von Abhängigkeiten in den Dokumenten.

Gibt es etwas, das ich in der Branche nicht kenne, das Programmierer dazu bringt, keine Dokumentation zu schreiben? Ich kann bei Bedarf Absätze von Dokumenten ausschreiben. Warum sind andere dem so abgeneigt?

Was noch wichtiger ist, wie kann ich sie davon überzeugen, dass das Schreiben von Dokumenten uns in Zukunft Zeit und Frust ersparen wird?

Rudolf Olah
quelle
13
Weil wir wissen, was wir tun! Warum sollten wir uns die Zeit nehmen, aufzuschreiben, was wir bereits wissen und nie vergessen werden!?!? Im Ernst, ich beschäftige mich täglich mit dem gleichen Thema und arbeite an einer Codebasis, die vor 7 Jahren ihren Entwurfsprozess begonnen hat und seitdem täglich von einem Team von 4 bis 7 Ingenieuren aktualisiert wurde. Dokumentation ist etwas, mit dem wir immer zu kämpfen hatten, aber es ist ein notwendiges Übel.
Ampt
61
Denn die Erfahrung hat gezeigt, dass niemand die Dokumente liest.
user16764
7
Aus geschäftlicher Sicht kostet jede Menge Dokumentation das Unternehmen hier und jetzt Geld, wenn Sie stattdessen am nächsten Projekt arbeiten könnten, um Geld zu verdienen. Das Erzielen eines Gewinns ist der Druck, der gegen die "Verschwendung von Zeit" beim Verfassen von Dokumenten besteht. Außerdem liest niemand jemals die Dokumente und liest stattdessen die Quellen, weil nur sie die ultimative Autorität sind.
Patrick Hughes
14
Das Synchronisieren der Dokumente mit dem neuesten Code kann eine "Herausforderung" sein, wenn Sie auf einer höheren Ebene als Javadoc oder einer vergleichbaren Ebene schreiben.
Dan Pichelman
12
Es macht keinen Spaß ...

Antworten:

21

Ich denke nicht, dass es hilfreich ist, über die Motivation von Menschen zu spekulieren, die etwas nicht übernehmen, von dem Sie glauben, dass es eine gute Praxis ist, oder die weiterhin etwas tun, das Sie als schlechte Praxis ansehen. In diesem Geschäft sind die Leute, die in eine oder beide dieser Kategorien fallen, weitaus zahlreicher als die, mit denen Sie sich auf Augenhöhe sehen werden. Machen Sie sich also nicht mehr verrückt.

Konzentrieren Sie sich stattdessen auf das Problem und mögliche Lösungen.

1. Schreiben Sie selbst eine gute Dokumentation

Es ist möglicherweise nicht realistisch zu erwarten, dass jeder in Ihrem Team seine Anstrengungen auf die Dinge richten wird, die Sie als Problem ansehen. Dies gilt insbesondere dann, wenn Sie ein relativer Neuling im Team sind. Ich wage zu vermuten, dass Sie es sind, denn wenn Sie ein Gründungsmitglied des Teams wären, wäre es sehr wahrscheinlich, dass Sie dieses Problem bereits zu einem frühen Zeitpunkt gelöst haben.

Erwägen Sie stattdessen, auf das Ziel hinzuarbeiten, selbst gute Dokumentationen zu schreiben und die Leute dazu zu bringen, diese zu verwenden. Wenn mich zum Beispiel jemand in meinem Team fragt, wo der Quellcode für Projekt A ist oder welche spezielle Konfiguration Projekt A benötigt, verweise ich ihn auf die Wiki-Seite für Projekt A.

Wenn mich jemand fragt, wie man eine neue Implementierung von Factory F schreibt, um ein Objekt für Client C anzupassen, sage ich ihm, dass es sich auf Seite 10 des Entwicklerhandbuchs befindet.

Die meisten Entwickler hassen es, Fragen zu stellen, bei denen sie den Eindruck haben, dass sie den Code nicht mehr "lesen" können, als Dokumentation zu lesen. Nach einer ausreichenden Anzahl solcher Antworten werden sie daher zuerst die Dokumente lesen.

2. Beweisen Sie den Wert Ihrer Dokumentation

Stellen Sie sicher, dass Sie jede Gelegenheit nutzen, um darauf hinzuweisen, wo die Dokumentation ihren Wert beweist (oder hätte, falls verwendet). Versuche subtil zu sein und vermeide "Ich habe es dir gesagt", aber es ist absolut legitim Dinge wie zu sagen

Zum späteren Nachschlagen enthält die Wiki-Seite dieses Projekts Informationen über den Zweig des Kerncodes, der für die fortlaufende Unterstützung von Version 2.1 erstellt wurde. In Zukunft müssen wir also keinen vollständigen Regressionstest mehr durchführen, wenn Personen, die veröffentlichte Versionen verwalten, dies überprüfen das Wiki vor dem Auschecken des Codes.

oder

Ich bin so froh, dass ich die Schritte für die Durchführung von Aufgabe T aufgeschrieben habe. Es ist mir egal, ob es jemals jemand anderes verwendet - es hat mir bereits mehr Zeit gespart als das, was ich damit verbracht habe.

3. Holen Sie das Management an Bord

Nach einigen Vorfällen, bei denen nachweislich Zeit und Geld gespart werden, werden Sie wahrscheinlich ein deutliches "Auftauen" der Dokumentation bemerken. Dies ist der richtige Zeitpunkt, um die Dokumentationszeit in Ihre Schätzungen einzubeziehen (obwohl ich normalerweise Dokumente aktualisiere / erstelle, während lange Prozesse ausgeführt werden, wie z. B. Kompilierungen oder Einchecken). Insbesondere wenn es sich um eine kürzlich eingestellte Anstellung handelt, wird dies möglicherweise nicht in Frage gestellt, sondern als neue Praxis angesehen, die Sie von einem früheren Arbeitsplatz (der möglicherweise vorhanden ist) einbringen.

Ein Wort der Vorsicht: Die meisten Vorgesetzten möchten nicht, dass Menschen etwas tun, insbesondere Dinge, die nicht direkt mit einer abrechenbaren Aufgabe verbunden sind. Erwarten Sie daher nicht, dass diese Unterstützung in Form eines Mandats erfolgt. Stattdessen ist es wahrscheinlicher, dass Sie relativ freie Hand haben, um mehr Dokumente zu schreiben.

4. Fördern Sie die Dokumentation, wenn Sie sie sehen

Vielleicht ist einer der Gründe, warum die Leute nicht so oft Dokumente schreiben, wie sie sollten, das Gefühl, dass niemand sie liest. Wenn Sie also etwas sehen, das Ihnen gefällt, sollten Sie zumindest erwähnen, dass Sie froh waren, dass es verfügbar war.

Wenn Ihr Team Codeprüfungen durchführt, ist dies eine Zeit, in der Sie ein oder zwei subtile Wörter eingeben können, um zu guten Kommentaren anzuregen.

Vielen Dank, dass Sie die Problemumgehung für Fehler B in Framework G dokumentiert haben. Ich wusste nichts davon, und ich glaube nicht, dass ich hätte verstehen können, was Sie ohne das getan haben.

Wenn Sie jemanden im Team haben, der wirklich von Dokumentation begeistert ist , schadet es nicht, diese Person zu kultivieren, indem Sie zum Mittagessen oder Kaffee gehen und sicherstellen, dass Sie eine kleine Bestätigung anbieten, um der Entmutigung entgegenzuwirken, die sie durch das Sehen des Restes des Teams erhalten könnten schätzt die Dokumentation nicht so sehr.

Darüber hinaus ist es nicht wirklich Ihr Problem, es sei denn, Sie sind in einer Führungsposition. Sie können ein Pferd zum Wasser führen, aber Sie können es nicht zum Trinken bringen. Wenn es nicht dein Pferd ist, bist du vielleicht nicht froh, dass es durstig ist, aber alles, was du tun kannst, ist den Trog zu füllen.

Amy Blankenship
quelle
1
+1 für Punkt # 2, direkte Beantwortung der Frage des OP, die mit "Wie kann ich überzeugen ..." beginnt
Ray Toal
Ich mag diese Antwort, die anderen konzentrierten sich mehr auf das "Warum" anstelle des "Wie"
Rudolf Olah
@omouse - das liegt daran, dass das Schreiben von Dokumenten in den meisten Fällen keine Zeit und keine Frustration in der Zukunft spart. Sie sind selten genau, und die Leute lesen sie nie, selbst wenn sie es sind.
Telastyn
1
SOLID-Prinzipien sparen normalerweise keine Zeit und führen auch nicht zu einem besseren Design, da die meisten Leute sie entweder nicht vollständig verstehen oder nicht wirklich scheißen. Nach Ihrer Logik sollten wir nicht danach streben, sie, GRASP oder andere bewährte Praktiken anzuwenden. Erinnern Sie mich daran, warum Sie sich die Mühe machen, wieder an Programmierern teilzunehmen?
Amy Blankenship
Ich finde es sehr hilfreich, über die Motivation der Leute zu spekulieren.
Tymtam
55

Nach meiner Erfahrung gibt es zwei Hauptfaktoren:

Fristen

Die meisten Unternehmen sind so datumsorientiert, dass Qualitätssicherung, technische Verschuldung und tatsächliches Design reduziert werden, damit der Projektmanager nicht schlecht aussieht oder eine absurde, zu viel versprochene Kundenfrist einhält. In diesem Umfeld, in dem sogar die funktionale Qualität beeinträchtigt wird, hat eine langfristige Investition wie die Dokumentation nur geringe Chancen.

Veränderung

Eine relativ neue Best Practice für Entwickler besteht darin, Kommentare zu deaktivieren. Die Idee ist, dass das Speichern von Informationen an zwei Stellen (dem Code [einschließlich Tests] und den Kommentaren rund um den Code) zu einem erheblichen Mehraufwand führt, wenn sie für einen geringen Nutzen synchronisiert werden. "Wenn Ihr Code so schwer zu lesen ist, dass Sie Kommentare benötigen, wäre es nicht besser, die Zeit damit zu verbringen, den Code zu bereinigen?"

Ich persönlich werde mir nicht einmal mehr Kommentare ansehen. Code kann nicht lügen.

Dokumentation folgt der gleichen Ader. Mit der weit verbreiteten Einführung von Agile erkennen die Menschen, dass sich die Anforderungen regelmäßig ändern. Mit dem weit verbreiteten Einsatz von Refactoring wird sich die Organisation des Codes erheblich verändern. Warum die Zeit damit verbringen, all diese Dinge zu dokumentieren, die sich zwangsläufig ändern werden? Code und Tests sollten dabei gute Arbeit leisten.

Telastyn
quelle
11
+1 für "Ich persönlich sehe mir noch nicht einmal mehr Kommentare an", denke ich, dass dies üblich ist. Wenn Sie mit dem Code selbst ein bestimmtes Komfortniveau erreichen, können Sie ihn schneller lesen als die Kommentare (und noch schneller, wenn die Kommentare nicht im Weg sind), und der Code lügt nicht
Jimmy Hoffa
40
Dies geht am Punkt der Kommentare vorbei, um zu erklären, warum . Sie müssen nicht allgegenwärtig sein, und sie müssen nicht sehr lang sein, aber ein gut platzierter Link zu den Geschäftsregeln, die beschreiben, warum die nächsten 20 Zeilen wirklich bizarrer Logik in ihrem aktuellen Zustand existieren, ist viel mehr Praktisch, als den Versionsverlauf zu durchsuchen, um die ursprüngliche Argumentation zu finden.
zzzzBov
7
@zzzzBov - das ist absolut die moderne Sicht der Dinge. Dies hat sich im Vergleich zu früheren Standpunkten geändert, was zu umfassenderen Kommentaren geführt hat. Ebenso wurde die Dokumentation dessen, was der Code tut, auf eine Dokumentation reduziert, die sich darauf konzentriert, warum er es tut (z. B. Designdokumente).
Telastyn
8
Code kann lügen. Möglicherweise wollte der Kunde etwas, und es wurde programmiert, etwas anderes zu tun. Wenn Sie jetzt nur den Code haben, stimmt das?
Donnerstag,
6
Code kann lügen ... Ich habe eine 4.000-Zeilen-Methode (hey, ich habe sie nicht erstellt, ich besitze sie gerade ...) und ich sehe eine Sammlung mit dem eindeutigen Namen "productList", also füge ich für eine neue Änderung ein Produkt hinzu Einwände dagegen. Toll. Es funktioniert nur nicht, es stellte sich heraus, dass einige Entwickler in der Vergangenheit "effizient" waren und die Variable vom Listentyp wiederverwendeten, um zu vermeiden, dass die 4.000 Zeilen mit zu vielen Variablen überfüllt sind, und in diesem Bereich enthält sie Kundenobjekte ...
Kevin Rubin
16

Hier spielen eine Reihe von Faktoren eine Rolle:

  1. Gut geschriebener Code ist eine eigene Dokumentation. Wenn alle anderen Dinge gleich sind, ist es besser, klareren Code zu schreiben, der für sich selbst spricht, als mehr Dokumentation. Tun Sie das, und Sie müssen weniger Dokumentation ändern, wenn Sie diesen Code ändern.

  2. Das Schreiben von Dokumentation ist wohl eine andere Fähigkeit als das Schreiben von Code. Einige Softwareentwickler können das besser als andere. Einige können Code viel besser schreiben als sie Dokumentation schreiben.

  3. Die Dokumentation sollte nur einmal geschrieben werden müssen , nicht zweimal (einmal im Quellcode und noch einmal im Programmierhandbuch). Deshalb gibt es XML-Kommentare und Dokumentationsgeneratoren. Leider kann die Verwendung solcher Tools schwieriger und umständlicher sein, als nur die Dokumentation von Hand zu schreiben. Aus diesem Grund werden diese Tools nicht häufig verwendet.

  4. Gute Dokumentation ist zeitaufwändig und schwer zu erstellen. Wenn alle anderen Dinge gleich sind, kann das Schreiben von neuem Code mehr wert sein als das Schreiben von Dokumentation für bereits vorhandenen Code.

  5. Wenn sich der Code ändert, müssen Sie auch die Dokumentation ändern. Je weniger Dokumentation vorhanden ist, desto weniger muss geändert werden.

  6. Die Dokumentation wird sowieso von niemandem gelesen, warum also die Mühe machen?

Robert Harvey
quelle
2
Zu # 1, ich glaube nicht, dass das jemals der Fall ist, aber # 4 ist definitiv wahr
Rudolf Olah
3
@whatsisname: Überhaupt nicht. Schreiben Sie klareren Code, der weniger Dokumentation erfordert, und Sie müssen weniger Dokumentation ändern, wenn Sie diesen Code ändern.
Robert Harvey
2
@ thursdaysgeek: Diese Aufzählungszeichen bedeuten, dass Sie die Dokumentation nicht zweimal schreiben müssen: einmal für die Codekommentare und erneut für die Referenz der Hilfedatei / des Programmierers. Sie sollten es auf keinen Fall zweimal umschreiben müssen . Liest ihr das Ding?
Robert Harvey
4
# 6 ... Ich denke, das ist ein weit verbreitetes Missverständnis. Eine Menge Leute lesen gründlich Dokumentation.
Dynamische
3
@tymek: Du hast dein Zeichen verkehrt herum. Leute, dies ist kein Tutorial zum Erstellen von Dokumentation. Es ist eine Rechnung, warum Entwickler eine negative Einstellung dazu haben.
Robert Harvey
11

Elefant im Raum: Programmierer sind (nicht unbedingt) Schriftsteller. Sie sind auch nicht unbedingt dazu geeignet, ihre Implementierungen für technische Redakteure zu konkretisieren. Zweiter Elefant im Raum: Technische Redakteure sind im Allgemeinen nicht in der Lage, Details zu präzisieren, die für zukünftige Entwickler nützlich sind (selbst wenn die Entwickler sie ihnen gerne erklären würden).

Ein komplexes System kann ohne ordnungsgemäße Dokumentation im Laufe der Zeit nahezu undurchschaubar werden. Der Code wird umgekehrt proportional zu seiner Überprüfbarkeit weniger wertvoll. Das Management beauftragt einen Software-Ingenieur, der Code lesen und Details von Entwicklern abrufen kann, ihn mit einer Entwicklerrate vergütet und ihn mit der Dokumentation und Pflege der Dokumentation beauftragt. Dieser Schreiber kann Code lesen und weiß, welche Fragen zu stellen sind, und füllt bei Bedarf Details aus. Genau wie Sie eine QS-Abteilung haben, haben Sie eine interne Dokumentationsabteilung.

Der Code wird wertvoller, da Sie ihn an einen Dritten lizenzieren können (da er ihn verstehen kann). Der Code kann einfacher überprüft und verbessert / re-factored werden. Sie können den Code besser wiederverwenden, selbst dort, wo Sie es können Ziehen Sie einfachere Versionen Ihrer Software heraus, und Sie können neue Entwickler leichter in das Projekt einführen. Ihre Support-Ingenieure werden es lieben, für Sie zu arbeiten.

Das wird niemals passieren.

Naftalimich
quelle
1
Ganz zu schweigen davon, dass es beim Versuch, vorhandenen Code zu beschreiben, schwieriger wird, eine gute Beschreibung zu geben, wenn der Code und die Funktionalität so komplex sind, dass niemand weiß, was er bereits tut. Daher haben alle neuen Änderungen Auswirkungen, die der neue Entwickler nicht hat Wissen über ...
Kevin Rubin
1
Ich würde vorschlagen, dass "grundlegende Fähigkeit, seine oder ihre Absichten mit (begrenzter) Dokumentation zu kommunizieren" eine notwendige Programmiererfähigkeit ist. Ein Programmierer muss kein Dichter sein, aber wenn er oder sie nicht dokumentieren kann, möchte ich ihn ehrlich gesagt nicht in meinem Team haben. Eine solche Person ist langfristig haftbar.
5

Was noch wichtiger ist, wie kann ich sie davon überzeugen, dass das Schreiben von Dokumenten uns in Zukunft Zeit und Frust ersparen wird?

Tut es das?

Es gibt zwei Arten von Dokumentation:

Nützliche Dokumentation

Dokumentiert, wie ein fertiges Produkt, eine API, welche IP-Adressen oder URL-Namen unsere Server haben usw. verwendet werden. Grundsätzlich alles, was intensiv und täglich verwendet wird. Falsche Informationen werden schnell gefunden und korrigiert. Muss leicht zu finden und leicht zu bearbeiten sein (zB Online-Wiki).

Nutzlose Dokumentation

Dokumentation, die sich oft ändert, nur sehr wenige Menschen interessieren sich dafür und niemand weiß, wo man sie findet. Wie der aktuelle Status eines Features, das implementiert wird. Oder Anforderungsdokumente in einem Word-Dokument, das irgendwo in SVN versteckt ist und vor 3 Jahren aktualisiert wurde. Das Schreiben dieser Dokumentation wird einige Zeit in Anspruch nehmen und später herausfinden, dass sie falsch ist. Sie können sich nicht auf diese Art von Dokumentation verlassen. Es ist nutzlos. Es verschwendet Zeit.

Programmierer mögen es nicht, unnütze Dokumentationen zu schreiben oder zu lesen. Wenn Sie ihnen jedoch eine nützliche Dokumentation zeigen können, schreiben sie diese. In meinem letzten Projekt hatten wir großen Erfolg damit, als wir ein Wiki einführten, in dem wir alle Informationen schreiben konnten, die wir oft benötigen.

Uooo
quelle
4

Ich würde sagen, dass der Hauptgrund ein Mangel an Willen und ein Mangel an Verständnis für die Funktion der Dokumentation ist. Es gibt eine Reihe von Dokumentationsklassen, die berücksichtigt werden müssen:

Produkt- / Release-Dokumentation

Dies ist alles, was mit Ihrem "fertigen" Produkt ausgeht. Dies ist mehr als nur Handbücher, das sind READMEs, Change Logs, HOW-TOs und dergleichen. Theoretisch kann man davonkommen, diese nicht zu schreiben, aber am Ende hat man ein Produkt, das die Leute nicht nutzen wollen, oder eine Supportlast, die unnötig teuer ist.

API-Dokumentation

Dies beschreibt etwas, das relativ statisch sein sollte. Da zahlreiche Konsumenten möglicherweise für Ihre API codieren, sollte diese ausreichend stabil sein, damit eine Prosa, die beschreibt, wie sie verwendet wird, einen Wert hat. Wenn Sie beschreiben, welche Parameter unterstützt werden, wie der Rückgabewert sein kann und welche Fehler möglicherweise auftreten, können andere Benutzer Ihre API auf der richtigen Abstraktionsebene verstehen - der Schnittstelle ( nicht der Implementierung).

Code-Kommentare

Die Meinung der Branche zu Kommentaren scheint derzeit im Fluss zu sein. Als ich anfing, professionell zu programmieren, waren Kommentare eine unabdingbare Voraussetzung für das Schreiben von Code. Jetzt ist es Mode, Code zu schreiben, der so klar ist, dass keine Kommentare erforderlich sind. Ich würde vermuten, dass dies teilweise auf die Tatsache zurückzuführen ist, dass viele moderne Sprachen auf einer viel höheren Ebene geschrieben sind und es viel einfacher ist, lesbaren Code in Java, JavaScript, Ruby usw. zu schreiben als in Assembler , C, FORTRAN usw. Daher hatten Kommentare einen viel größeren Wert.

Ich glaube immer noch, dass Kommentare Wert haben, die die Absicht eines Codeabschnitts beschreiben, oder einige Details darüber, warum ein bestimmter Algorithmus einem offensichtlicheren vorgezogen wurde (um zu vermeiden, dass eifrige Unholde den Code "reparieren", der dies nicht tut). muss eigentlich behoben werden).

Leider gibt es eine Menge Selbstsucht, Rationalisierung und Selbsttäuschung bei den Entscheidungen der Programmierer, nicht zu dokumentieren. Die Realität ist, dass, wie beim Code, andere Personen das primäre Publikum für die Dokumentation sind. Die Entscheidung, Dokumentation auf jeder Ebene zu schreiben (oder nicht zu schreiben), sollte daher auf Teamebene getroffen werden. Für die höheren Abstraktionsebenen ist es möglicherweise sinnvoller, andere Personen als Entwickler zu beauftragen, dies zu tun. In Bezug auf die Dokumentation auf Kommentarebene sollte eine Einigung über den Zweck und die Absicht der Kommentare erzielt werden, insbesondere in Teams mit gemischten Fähigkeiten und Erfahrungen. Es ist nicht gut, wenn erfahrene Entwickler Code schreiben, an den sich Junior-Entwickler nicht wenden können. Einige gut platzierte und gut geschriebene Dokumente ermöglichen es einem Team, viel effektiver zu arbeiten

Dancrumb
quelle
1
+1 für "Die primäre Zielgruppe für die Dokumentation sind andere Personen". Zu viele Programmierer nicht wirklich die Kommunikation mit anderen zu schätzen wissen . (Das ist auch der Grund, warum es ihnen schwer fällt, im Dienstalter voranzukommen.)
Donal Fellows,
4

Hier sind meine zwei Cent.

  1. Das Agile Manifest besagt "Software über umfassende Dokumentation arbeiten" und nicht jeder liest weiter, um zu erreichen "Das heißt, während es Wert in den Gegenständen auf der rechten Seite gibt, schätzen wir die Gegenstände auf der linken Seite mehr."

  2. Leider ist es bei https://en.wikipedia.org/wiki/Code_and_fix üblich, und die Dokumentation funktioniert mit diesem Modell nicht (es ist nicht synchron).

  3. Die Softwareentwicklungsbranche ist nicht gut reguliert. Es besteht keine gesetzliche Verpflichtung, Unterlagen zu verfassen.

  4. Selbstdokumentierender Code ist der aktuelle Trend.

Trotzdem denke ich, dass es eine Menge guter Dokumentationen gibt.

tymtam
quelle
(1) " Wir schätzen die Dinge auf der linken Seite mehr ... " bedeutet nicht, dass uns die rechte Seite überhaupt nicht wichtig ist. (2) " 4. Selbstdokumentierender Code ist der aktuelle Trend " Wenn Dokumentation dann nicht erforderlich ist, warum beklagen sich dann die Leute in erster Linie über eine schlechte / fehlende Dokumentation? (3) Die Zeit, die ein Entwickler spart, wenn er seine Arbeit nicht dokumentiert, wird von jedem einzelnen Entwickler aufgewendet , der die Informationen benötigt, da er 5000 Zeilen selbstdokumentierenden Code anstelle von 5 Seiten Dokumentation scannen muss. Effizienz ist etwas anderes, aber hey, wir sind agil!
JensG
2

Dokumentation braucht Zeit, und ich vermute, dass viele Entwickler zu viele Run-Ins mit Dokumentation hatten, die schlimmer als nutzlos war. Sie haben die Idee, dass ihnen nicht nur die Dokumentation von ihrem Vorgesetzten Ärger einbringt (derselbe, der den QS-Teil des Zeitplans immer wieder kürzt), sondern auch niemandem, auch ihnen, hilft.

Jede halbwegs anständige Dokumentation ist eine Investition in die Zukunft. Wenn Sie sich nicht für die Zukunft interessieren (weil Sie nicht über den nächsten Gehaltsscheck hinaus denken oder weil Sie denken, dass dies nicht Ihr Problem ist), ist der Gedanke, die Dokumentation zu erstellen, äußerst schmerzhaft.

Michael Kohne
quelle
2

Viele der anderen Antworten lassen den Schluss zu, dass es mindestens zwei Arten von Dokumentationen gibt: eine für andere Entwickler und eine andere für Endbenutzer. Abhängig von Ihrer Umgebung benötigen Sie möglicherweise zusätzliche Dokumentation für Systemadministratoren, Installateure und Helpdesk-Mitarbeiter. Jedes Zielpublikum hat unterschiedliche Bedürfnisse und Verständnisniveaus.

Betrachten Sie den (Stereo-) typischen Entwickler: Er ist ein Codierer nach Wahl. Er hat eine Karriere außerhalb der Öffentlichkeit gewählt und verbringt viele Stunden hinter einer Tastatur, die in erster Linie mit sich selbst kommuniziert. Der Dokumentationsprozess ist eine Form der Kommunikation, und die Fähigkeiten, die für die Erstellung einer guten Dokumentation erforderlich sind, stehen den Fähigkeiten, die für die Erstellung eines guten Codes erforderlich sind, entgegen.

Ein guter Dokumentationsschreiber kann in mehreren Sprachen kommunizieren: in der Sprache der Benutzer, in der Sprache des Managements, in der Sprache des Support-Personals und in der Sprache der Entwickler. Es ist die Aufgabe eines Dokumentationsschreibers, zu verstehen, was ein Codierer kommuniziert, und dies in eine Form zu übersetzen, die alle anderen Gruppen verstehen können.

Wenn Sie davon ausgehen, dass Codierer die Fähigkeiten entwickeln, die erforderlich sind, um gute Kommunikatoren zu werden (schriftlich oder auf andere Weise), wird die Zeit, die zum Honen der primären Fähigkeiten (Codierung!) Aufgewendet wird, verringert. Je weiter er von seiner Komfortzone entfernt ist (Codieren und Kommunizieren mit anderen Codierern), desto mehr Zeit und Energie wird benötigt, um die Aufgabe gut auszuführen. Es ist zu erwarten, dass sich ein professioneller Programmierer auf Kosten aller anderen hauptsächlich auf seine Kernkompetenzen konzentrieren möchte.

Aus diesem Grund sollte die Dokumentation (mit Ausnahme von Inline-Code-Kommentaren) den Kommunikatoren und nicht den Codierern überlassen werden.

George Cummins
quelle
4
Oh, scheiß drauf. Je mehr Dinge du lernst, umso besser lernst du, Dinge gut zu machen. So wie Menschen, die mehrere Sprachen beherrschen, besser programmieren als Menschen, die nur eine Sprache kennen (weil sie mehr Möglichkeiten kennen, über das Problem nachzudenken), erhalten Sie durch die Fähigkeit, grafisch zu schreiben und sogar zu visualisieren mehr Werkzeuge, um über Probleme nachzudenken und sie zu lösen. Die Fähigkeiten , müssen Sie in der Lage sein , zu beschreiben , was die gleichen , die geschieht Sie herauszukitzeln brauchen werden , was sollte passieren.
Amy Blankenship
1
Ich möchte, dass andere Entwickler qualifizierte Kommunikatoren sind oder werden. Die überwiegende Mehrheit der Programmierung, die wir durchführen (zumindest in Unternehmenssoftware), erfordert nicht die absoluten höchsten Kodierungsfähigkeiten. Es erfordert viel bessere persönliche Kommunikationsfähigkeiten, damit zukünftige Entwickler verstehen, was geschrieben wurde. Je besser ein Entwickler kommunizieren kann, insbesondere mit Leuten, die er niemals trifft, desto besser wird er auf lange Sicht angesprochen und wahrscheinlich nicht für cleveren Code.
Kevin Rubin
2

Das Lesen des Codes zeigt Ihnen, wie es funktioniert. Es kann nicht erklären, warum : Sie brauchen Kommentare.

Wenn Sie den Code lesen, sehen Sie den Namen einer Methode und die Typen der Parameter. Es kann nicht die Semantik oder die genaue Absicht des Autors erklären: Sie brauchen Kommentare.

Kommentare ersetzen nicht das Lesen des Codes, sie ergänzen ihn.

benlast
quelle
4
+1 für das Gefühl. Dies ist jedoch keine Antwort auf die Frage. Sie scheinen hier auf etwas anderes zu antworten als auf die tatsächlich gestellte Frage.
Großartige
2

Die Dokumentation wird nicht so ausgeführt, wie der Code ist. Infolgedessen gibt es häufig keine wirksamen Rückkopplungsschleifen, um zu überprüfen, ob die Dokumentation vorhanden und vollständig ist. Dies ist der gleiche Grund, warum Codekommentare dazu neigen, zu verrotten.

Donald Knuth warb für Literate Programming , um die Qualität der Software zu verbessern und die Dokumentation effektiv mit dem Code zu schreiben. Ich habe einige Projekte gesehen, die diesen Ansatz sehr effektiv genutzt haben.

Persönlich versuche ich, mich an den modernen Trend zu halten, die öffentliche API Ihres Codes so lesbar wie möglich zu halten, und Unit-Tests zu verwenden, um die Verwendung für andere Entwickler zu dokumentieren. Ich denke, dies ist Teil der größeren Idee, dass Ihre API eine Form hat, die erforscht und entdeckt werden kann. Ich denke, dieser Ansatz ist Teil dessen, was HATEOAS mit Webdiensten erreichen will .

aboy021
quelle
Um meine Wahl für die automatisierte Generierung von Dokumentation zu rechtfertigen, habe ich eine Scheinformel entwickelt, um zu zeigen, wie die Trägheit des Menschen der Schuldige aller Kommentare ist. Bei der Erweiterung des Arguments stellte ich fest, dass das Erstellen von Methoden, die einem Entwickler tatsächliche Vorteile bieten, wie z. B. die teilautomatisierte Generierung von Diagrammen aus Metakommentaren im Quellcode, in der Regel jedes Mal aktualisiert wird, wenn ein Entwickler versucht, den Code zu verstehen. Übrigens ist dieser Entwickler meistens nur "Future Me".
Wolfmanx
0

Ein kleiner Punkt, der jedoch bei einigen Entwicklern wichtig zu sein scheint, die unangenehm wenig Dokumentation schreiben: Sie können nicht tippen. Wenn Sie eine Annäherung an das 10-Finger-System haben, neigen Sie dazu, mehr Dokumentation zu schreiben, nur weil es einfach ist. Aber wenn Sie beim Jagen und Picken stecken bleiben, sind Sie verloren. Wenn ich für die Einstellung verantwortlich wäre, würde ich das überprüfen.

Hans-Peter Störr
quelle
0

Menschen, die nicht gerne Dokumentation lesen, schreiben nicht gerne Dokumentation. Viele Programmierer werden alles tun, um ein gründliches Lesen eines Dokuments zu vermeiden.

Konzentrieren Sie sich nicht auf das Schreiben, sondern auf das Lesen. Wenn Programmierer die Dokumentation lesen und die Dinge daraus assimilieren, erkennen sie den Wert und neigen viel mehr dazu, einige zu schreiben.

Joeri Sebrechts
quelle
-1

Als ich meinen jetzigen Job antrat und ein Hardware + Software-Projekt von den Leuten übernahm, die zuvor daran gearbeitet hatten, erhielt ich ein etwa hundertseitiges Word-Dokument, das das System beschreibt. Die Produktion muss Tage gedauert haben. Ich habe es mir vielleicht zweimal angesehen. Trotz der riesigen Menge an Informationen, die sich darin befanden, beantwortete es selten die tatsächlichen Fragen, die ich zu dem System hatte, und selbst wenn dies der Fall war, war es schneller, sich den Code anzusehen.

Nach genug solcher Erfahrungen fängt man an zu überlegen, warum sich die Mühe machen? Warum verbringen Sie Ihre Zeit mit der Beantwortung von Fragen, die nie gestellt wurden? Sie beginnen zu begreifen, wie schwierig es wirklich ist, vorherzusagen, nach welchen Informationen die Benutzer in der Dokumentation suchen werden. Es ist unweigerlich mit Fakten gefüllt, die sich als nutzlos, unklar oder offensichtlich herausstellen und auf die dringendsten Fragen keine Antwort finden. Denken Sie daran, dass das Erstellen nützlicher Dokumentationen eine Anstrengung ist, menschliches Verhalten vorherzusagen. So wie es unwahrscheinlich ist, dass ein Benutzeroberflächendesign erfolgreich ist, bevor es mehrere Iterationen des Testens und Debuggens durchlaufen hat, ist es naiv anzunehmen, dass es möglich ist, nützliche Dokumentationen zu schreiben, die nur auf den Erwartungen basieren, wie und was Benutzer das System interpretieren Rolle, die die Dokumentation und ihre Sprache bei dieser Interpretation spielen.

Ich neige dazu zu denken, dass der größte Druck, Dokumentation zu schreiben, von der Tatsache herrührt, dass es eine unangenehme Aufgabe ist und die Leute sich gegenseitig gerne zu unangenehmen Aufgaben verleiten ("Sie haben Ihr Filboid Studge nicht gegessen!").

JEDOCH

Ich denke nicht, dass die Dokumentation in jeder Hinsicht hoffnungslos ist. Ich halte es in erster Linie für hoffnungslos, wenn die Leute die Dokumentation als eine zusätzliche Belastung ansehen, die vor Abschluss eines Auftrags zu bewältigen ist, als letzten Teil der Aufräumarbeiten, die durchgeführt werden müssen, und als Kontrollkästchen. Dokumentation ist etwas, mit dem Sie sich in den Aspekten Ihres Tages befassen sollten, die Sie sowieso immer tun. Ich denke, E-Mail ist eine besonders gute Möglichkeit, Dokumentation zu erstellen. Wenn Sie eine neue Funktion hinzufügen, schreiben Sie einigen Personen eine kurze E-Mail, in der Sie angeben, was es ist. Generieren Sie beim Zeichnen eines neuen Schemas ein PDF und senden Sie es an alle Interessenten. Die Vorteile von E-Mails sind:

  1. Die Leute checken normalerweise E-Mails, während niemand durch einen Ordner namens "doc" wedelt.

  2. E-Mail existiert im Kontext, umgeben von anderen E-Mails, in denen die Funktion und verwandte Funktionen sowie alles andere besprochen werden, was zu der Zeit vor sich ging.

  3. E-Mail ist kurz und fokussiert und hat eine Betreffzeile.

  4. E-Mail ermöglicht es den Leuten, die sich dafür interessieren, Fragen sofort zu stellen,

  5. E-Mails sind sehr durchsuchbar, da sie von den Nutzern für alle Zwecke verwendet werden und die Anzahl der E-Mail-Clients im Laufe der Jahre erheblich zugenommen hat.

  6. Wenn es sich um eine E-Mail handelt, weiß mindestens eine andere Person, wo sie zu finden ist.

Theoretisch sollte es scheinen, dass Kommentare im Code auch "Aspekte Ihres Tages sein sollten, die Sie sowieso immer tun", aber um ehrlich zu sein, lese ich niemals Kommentare im Code. Ich weiß nicht warum, aber sie sind nicht sehr hilfreich, vielleicht weil es an Kontext mangelt, den die E-Mail löst.

Owen
quelle
Mit Ausnahme von Nummer 4 ("Leute, denen es am Herzen liegt, Fragen sofort zu stellen") hat keiner der von Ihnen aufgelisteten E-Mail-Vorteile zuverlässig für mich funktioniert. 1: Menschen neigen dazu , E - Mail zu ignorieren, wenn es eine Menge , es ist 2: E - Mail neigt häufig zu verlieren Zusammenhang es in Nebenfragen zu begraben und overquoting 3: E - Mails sind viel zu oft lang / groß und neigen zu verlieren Fokus als Diskussion wird in Weitere Nebenprobleme und Betreffzeilen sind oft irrelevant / veraltet ("Re: WTF ist heute auf dem Server passiert?") ...
gnat
... 5: E - Mail - Suche stark von der Fähigkeit zu löschen Mails gefährdet ist, auch ein Merkmal jeden anständiges Mailer hat und jeder aktiver Mail - Benutzer verwendet eine Menge 6: siehe 5, wenn die E - Mail gelöscht wird, wird niemand in der Lage sein finde es (das einzige, worauf ich mich verlassen kann, ist das Durchsuchen meiner gesendeten Mails, und das nur, weil ich mich sehr bemühe, diese nicht zu löschen). Anders als E - Mail Lob (was mir ganz unberechtigt aussieht), machen Sie ein paar gute Punkte , obwohl
gnat
@gnat Ich nehme an, dass das Löschen von Unternehmen zu Unternehmen unterschiedlich sein kann. In meinem Unternehmen speichern wir alle E-Mails sowie Archive aller E-Mails früherer Mitarbeiter. Wenn eine neue Person mit einer Aufgabe beginnt, leiten wir alle zugehörigen E-Mails an diese Person weiter. Ich vermute einen Unterschied im Stil.
Owen
Ja, das hängt sehr vom Stil und der Kultur ab. Zwar ist "Bekämpfung der Löschung" durchaus machbar (und sogar technisch einfach durch Exportieren von E-Mail-Threads auf einen Server zu erreichen), doch Dinge wie die Fokussierung, die Relevanz der Betreffzeilen und das Zitieren auf vernünftige Grenzen sind höchst kulturelle Dinge, die einen erheblichen Aufwand erfordern und Entschlossenheit (und Managementunterstützung) zu pflegen ... Verglichen mit diesem Aufwand und insbesondere mit der Notwendigkeit eines mgmt-Buy-Ins kann es einfacher werden, Dinge wie Wiki / Code-Kommentare / Doc-Ordner zu pflegen
gnat