Ermittlung der richtigen Dokumentationsmenge

Wo ich derzeit arbeite, ist der allgemeine Ansatz -

Vermeiden Sie die Dokumentation so weit wie möglich

Dokumentieren Sie nur, wenn ein anderes Team es benötigt

Nur zur Verdeutlichung meine ich nicht die Codedokumentation - das tun wir, ich meine die gesamte Dokumentation rund um den Entwurfsprozess - wenn es sich um UML- oder DB-Schemata, Klassendiagramme und Word-Dokumente mit Spezifikationen und dergleichen handelt.

Ich werde den Grund meines Chefs auflisten, nicht zu dokumentieren:

1. Es ist zeitaufwändig - konzentrieren Sie sich auf die Implementierung
2. Wenn sich das Design ändert, sollte sich die Dokumentation ändern, doppelte Probleme
3. Am Ende erhalten Sie nur Hunderte von Seiten, die niemand lesen möchte, und niemand bearbeitet sie wirklich, sodass sie mit der Zeit nicht mehr aktuell sind
4. Es ist ein Schmerz - niemand will es wirklich tun

Jetzt ist mir klar, dass wir schneller arbeiten, aber ich erinnere mich auch an die Zeit, als ich hier ankam und direkt zu einem alten Code tauchte, ohne etwas zu verstehen.

Eigentlich bekomme ich den größten Teil dieses alten Codes immer noch nicht und manchmal sehe ich beim Einsteigen viele Patches von verschiedenen Entwicklern, die versuchen, kleine Änderungen vorzunehmen.

Ich denke wirklich, dass mangelnde Dokumentation diese Art von Patches und mangelndes Systemverständnis im weitesten Sinne fördert.

meine Frage ist:

Wie können wir die Dokumentation so ausbalancieren, dass wir kontinuierliches Wissen im Team fördern und trotzdem schnell und effizient sind?

Ich habe festgestellt, dass JEDE Dokumentation besser ist als KEINE Dokumentation. Die angemessene Menge hängt normalerweise davon ab, wie viel Zeit wir dafür benötigen oder wie sehr wir Support-Telefonanrufe und E-Mails hassen.

Es scheint, dass Ihre derzeitigen Teammitglieder einige unrealistische Erwartungen an ihre Erinnerungen haben oder sich für ihre Schreibfähigkeiten schämen und nicht bereit sind, zu üben.

Mir ist klar, dass ich hier in einer Minderheit bin (englischer Major, der in der Graduiertenschule in die Softwareentwicklung eingestiegen ist), da ich Dokumentation nicht als lästige Pflicht empfinde. Es ist ein wertvolles professionelles Werkzeug. Ich finde das Schreiben vielleicht nicht so schwierig wie einige meiner Kollegen, aber das liegt hauptsächlich daran, dass ich mehr Übung darin habe. Ich halte ein Projekt nicht für abgeschlossen, es sei denn, es enthält Dokumentation, und ich schreibe es normalerweise aus rein egoistischen Gründen: So kann ich den Leuten etwas zum Lesen geben, anstatt Anrufe und E-Mails anzunehmen, oder ich kann mich daran erinnern, worüber wir zuletzt gesprochen haben Monat oder so kann ich mich darauf beziehen, wie ich etwas getan habe, wenn ich es mitten in der Nacht unterstützen muss.

Der beste Weg, sich der Dokumentation zu nähern, besteht darin, sie so zu schreiben, wie Sie es möchten, genau wie das Schreiben von Testcode. Es ist erstaunlich, wie einige vorab geschriebene Vorlagen (mit Kopfzeilen, Codestubs usw.) die Dokumentation einfacher und schneller machen können. Auf diese Weise können Sie Änderungen erfassen, wenn dies geschieht, und Sie haben im Laufe der Zeit weniger Boden, den Sie abdecken müssen. Auf diese Weise sind Sie effizienter, da Sie bei Bedarf auf die Dokumentation zugreifen und diese auf dem Weg ändern können. Wenn Sie dies beispielsweise in einem Wiki tun, werden Aktualisierungen einfacher, und Sie können Probleme mit der Dokumentversion vermeiden, wenn die neueste und beste Version immer am selben Ort online ist, und Sie können einfach Links an Personen senden, die sie lesen müssen.

Wenn Sie ein wenig Zeit mit Dokumentieren verbringen, werden Sie ALLE schneller arbeiten, insbesondere wenn jemand Neues dem Team beitritt, da er nicht die ganze Zeit damit verbringen muss, alles herauszufinden. Das Herausfinden von Dingen macht Spaß, aber es macht keinen Spaß, wenn Sie es eilig haben, um die Produktion zu reparieren. Wir würden alle viel Zeit sparen, wenn wir alle noch ein paar Notizen schreiben würden.

Hat Ihr Team dieselben Probleme beim Testen oder Schreiben von Testcode? Wenn nicht, ist dies ein einfacher Verkauf.

Ihre Dokumentation ist in vielerlei Hinsicht nützlich:
1) Für Sie und Ihre Mitarbeiter, während Sie an dem Projekt arbeiten.

2) An Ihre Kunden. Eine Dokumentation (einschließlich Diagramme), die Sie Benutzern zeigen können, erleichtert Diskussionen in Besprechungen, insbesondere wenn Sie über komplizierte Systeme sprechen. Auch wenn die Dokumentation unvollständig ist, ist dies ein Ausgangspunkt.

3) An die Menschen, die Ihre Arbeit erben werden (in drei Jahren können Sie es sogar sein). Viele meiner jüngeren Mitarbeiter denken, dass sie sich für immer an Dinge erinnern werden. Ich weiß, ich werde mich nach dieser Woche nicht mehr daran erinnern, wenn ich es nicht aufschreibe. Wenn Sie über eine Dokumentation verfügen, müssen Sie keinen halben Tag damit verbringen, sich daran zu erinnern, wie Sie etwas strukturiert haben, und alles erneut herausfinden.

4) Für Sie und andere, wenn die Situation politisch oder umstritten wird. Als jemand, der sich in Besprechungen Notizen macht, um wach zu bleiben und Langeweile zu bekämpfen, war ich oft der einzige mit der schriftlichen Version einer Entscheidung. Die Person, die es aufgeschrieben hat, gewinnt den Streit. Erinnern Sie sich daran, wenn jemand das nächste Mal sagt: "Erinnern Sie sich an das Treffen, das wir im vergangenen Winter im Konferenzraum 4 hatten, als wir über X gingen? Fred war da, und wer ist dieser Typ aus dem Rechnungswesen?"

Bei meinen letzten Arbeitgebern hatten wir ein "Entwicklungs" -Wiki. Dort werden wichtige Funktionsblöcke (neuer Import / Export-Feed, Funktionsweise des Sicherheitssubsystems, Speicherort der hochgeladenen Dokumente im System usw.) dokumentiert. Es ist normalerweise ein obligatorisches Element, das vor dem Codeüberprüfungsschritt abgeschlossen werden muss. Normalerweise gibt es am Anfang ein bisschen Widerstand dagegen, aber sobald jemand ein paar Informationen nachschlagen muss und sie dort sind, haben Sie einen weiteren Konvertiten.

Das Schöne daran, es in einem Wiki-Format zu haben, ist, dass Sie viel weniger geneigt sind, all die hübschen Word-Formatierungen und dergleichen durchzuführen und einfach die tatsächlichen Informationen aufzuschreiben, die Sie zum Speichern benötigen. Mit den meisten (wenn nicht allen) Wiki-Paketen können Sie Dokumente oder Bilder (wie Visio UML-Diagramme oder UI-Drahtmodelle) hochladen, sodass Sie auch visuelle Elemente haben können.

Wie die meisten Dinge denke ich, sollten Sie versuchen, die Mindestmenge zu tun, die möglicherweise funktionieren könnte. Das ist jedoch nicht dasselbe wie keines.

Sie können sich nicht entziehen, Zeit für das Schreiben der richtigen Dokumentation zuzuweisen. Stimmen Sie es ab, wie Sie möchten, je nachdem, wie viel Arbeit Sie erhalten, aber lassen Sie gut 15-20% Ihrer Zeit, um zu dokumentieren, was Sie getan haben. Jeder im Team muss dabei sein, einschließlich Ihres Managers, sonst dokumentieren Sie nur zum Nutzen anderer und erhalten keine Gegenleistung. Die Dokumentation muss ein wesentlicher Bestandteil Ihres Entwicklungsprozesses sein.

Die Dokumentation sollte Ihnen sagen, WARUM Sie etwas getan haben, während Sie den WIE-Teil dem eigentlichen Code und den WAS-Teil den Komponententests überlassen. Alles andere ist ein Schmerz. Dies ist normalerweise gut genug für kluge Leute, die nur einen Ausgangspunkt wollen.

Vergessen Sie auch nicht, für jede große Komponente Ihrer Codebasis eine allgemeine Architektur auf hoher Ebene beizubehalten. Erleichtert die Einführung neuer Teammitglieder.

Wenn Sie einen verrückten Fix hinzufügen, verlinken Sie schließlich aus einem Kommentar auf Ihre Fehlerdatenbank - sehr nützlich.

Ihr Chef hat Recht, drucken Sie keine UML-Dokumentation, die niemand lesen wird. In unserem Team navigieren wir mithilfe von Klassendiagrammansichten live im Modell. Das Prinzip besteht darin, MOF, das UML-Modell, immer vom Code zu aktualisieren und das Klassendiagramm nur als Betrachter des Modells, nicht aber des Modells selbst zu betrachten.

Es funktioniert sehr gut, da die gesamte Komplexität im Backoffice auf Modellebene erfolgt. Ich kann mein Projekt umgestalten, ein Java-Dokument schreiben oder eine Uml-Dokumentation in das Modell schreiben. Es ist eine Art Klick und Los. Wenn Sie auf klicken, erhalten Sie die Live-Dokumentation. Wenn etwas nicht klar ist, öffne ich das Klassendiagramm und beginne damit zu spielen. Aus Diagrammklassifizierern löschen, neue Klassifizierer hinzufügen, vergrößern und verkleinern, Zuordnung anzeigen, Zuordnung löschen usw. Das Modell wird nicht geändert, da ich keine neuen Modellinformationen erstelle, sondern sie nur verwende.

Es ist wirklich wichtig, das Diagramm eines Pakets zu öffnen und direkt im Klassendiagramm einen Kommentar darüber lesen zu können, was diese Klasse sein soll. Was soll diese Methode tun und was ist der Fluss etc ....

UML ist großartig, sehr hilfreich, aber wir sollten die Verwendung von Model Driven Devleopment einstellen, um mehr Flexibilität und Iteration in Modellierungs- / Entwicklungsphasen zu bieten. Das Klassendiagramm wird live aus dem Code aktualisiert und die Dokumentation ist immer korrekt und nur per Klick verfügbar. Ich werde kein Tool erwähnen, aber wenn Sie Java und Eclipse verwenden, ist es leicht zu finden, welches Tool ich verwende :-)