Was ist mit der Abneigung gegen Dokumentation in der Branche?

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?

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.

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.

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?

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.

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.

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

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.

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.

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.

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.

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 .

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.

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.

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.