Wo fange ich bei agilen Dokumentationen an und was sind die Best Practices für den Anfang?

Es gibt ein Anti-Pattern in vielen agilen Shops, wo sie nützliche Dokumentation abwerten, wahrscheinlich aufgrund der Überzeugung, dass „nur den Code lesen“ eine vernünftige Antwort ist.

Die kognitive Belastung für das Lesen einiger Codezeilen ist erheblich größer als die kognitive Belastung für das Lesen einiger Absätze von Wörtern; und wie heißt es so schön: ein bild sagt mehr als tausend worte. Als Programmierer sind Sie sicherlich schon auf Situationen gestoßen, in denen Sie Stunden damit verbracht haben, sich durch eine Codebasis zu wühlen, nur um schließlich jemanden zu fragen, der in der Lage ist, das Problem, das Sie zu lösen versuchen, mit ein paar Kästchen und Pfeilen auf einem Whiteboard zu veranschaulichen .

Allerdings kann eine vorzeitige Dokumentation ebenso wie eine vorzeitige Abstraktion ein Anti-Muster sein. Stattdessen ist hier der Prozess, den ich durchlaufe, wenn ich Produkt- und Entwicklungsteams leite:

1. Dokumentation ist der erste Schritt zur Automatisierung. Wenn Sie die Wörter nicht aufschreiben oder ein Bild von etwas zeichnen können, wird es sehr schwierig sein, es zu automatisieren.
2. Tests können Dokumentation sein, aber Tests sind standardmäßig keine Dokumentation . it { is_expected.to return 200 }sagt Ihnen nichts darüber aus, was der erwartete Endpunkt ist, was er akzeptieren soll oder was er zurückgeben soll.
3. Dokumentation ist am besten, wenn sie das Unsichtbare ergänzt . In JavaScript und Ruby verwende ich zum Beispiel Dokumentation als Ersatz für die expliziten Eingabe- und Ausgabe-Rückgabetypen von Java/C#.
4. Optimieren Sie Ihre Dokumentation für das Onboarding neuer Teammitglieder und Benutzer . Sie bekommen vielleicht nicht jeden Tag ein neues Teammitglied, aber die Informationen, die für Leute am nützlichsten sind, die die Codebasis/das Feature/das Modul/die Bibliothek zum ersten Mal öffnen, sind auch die nützlichste Dokumentation, wenn Sie darauf zurückkommen in ein paar Monaten und kann mich nicht mehr genau erinnern, was die Motivation für die Bibliothek überhaupt war.
5. Wenn es veraltet ist, löschen Sie es! Genauso wie Sie toten Code löschen. Lieber über fehlende als über irreführende Dokumentation stolpern!
6. In diesem Sinne sind wegwerfbare Diagramme manchmal besser als bearbeitbare. Einwegdiagramme haben oft eine geringere Wiedergabetreue und sind auf ihre Essenz reduziert, während bearbeitbare Diagramme aufgrund von Überspezifität veraltet sind. Einer meiner Kollegen zeichnet Diagramme auf A3-Blatt und fotografiert sie ab. Ich ziehe es vor, mein iPad zu verwenden, um Dinge mit einer Zeichen-App zu skizzieren. In jedem dieser Fälle besteht das Ziel darin, Dinge aus unseren Köpfen in die Welt zu bringen, die ohne nennenswerte Kosten nachgebaut werden können.

Ich hoffe das hilft!

Code ist Ihre nützlichste Dokumentation, da es das einzige Dokument ist, das immer auf dem neuesten Stand ist. Stellen Sie sicher, dass Ihr Code leicht lesbar ist: gut strukturiert, gut benannt und bei Bedarf kommentiert.

Erstellen Sie darüber hinaus die Dokumente, die Sie für notwendig halten. Es gibt keine feste Regel wie „Klassendiagramme sind ein Muss“ oder „Sequenzdiagramme sind Ihre Zeit nicht wert“. Bedenken Sie einfach Folgendes:

• Die Zeit, die Sie mit der Erstellung eines Dokuments verbringen, ist nicht kostenlos
• Ihr Produkt wird sich weiterentwickeln und dieses Dokument schließlich ungültig machen (Es ist grundsätzlich nichts falsch daran, eine Dokumentation mit begrenzter Haltbarkeit zu erstellen. WENN der unmittelbare Nutzen die Gesamtkosten überwiegt).
• Die Zeit, die zum Aktualisieren und Verwalten Ihres Dokuments erforderlich ist, ist ebenfalls nicht kostenlos
• Das Dokument ist nur nützlich, wenn es gelesen wird.
  • Ohne Notwendigkeit ist die obige Anstrengung verschwendet
  • Wenn die gleichen Informationen schneller durch Lesen des Codes gesammelt werden könnten, ist der obige Aufwand ebenfalls verschwendet (klassisches Beispiel: API-Dokumente, die einfach den Funktionsnamen wiederholen)
  • Wenn Ihre Dokumentation nicht gefunden werden kann, ist auch Ihre Mühe verschwendet (ich habe zu viel Dokumentation irgendwo tief in einem verwirrenden Ordnerwald auf einem nicht indizierten Netzlaufwerk gesehen, wo niemand, der den Inhalt nicht bereits kennt, sie jemals finden wird)

Das soll nicht heißen, dass Dokumentation niemals nützlich ist. Erstellen Sie Dokumentationen für die Dinge, die wirklich schwer herauszufinden oder festzunageln waren. Gehen Sie Ihre Notizblöcke durch. Wahrscheinlich haben Sie bereits zahlreiche Notizen zu diesen Themen, als Sie sich das erste Mal damit beschäftigt haben.

Die einzige Ausnahme sind meiner Meinung nach Anforderungen: Sie sollten immer ein detailliertes und klares Dokument haben, in dem Ihre Anforderungen erläutert werden. Egal, wie trübe das Wasser dort ist, wo du dich gerade befindest, du solltest immer wissen, wohin du gehst (sollst).

• Dokumentieren Sie Ihre Prozesse, nehmen Sie alle Dinge auf, die Ihnen wirklich wichtig sind.
• Bleiben Sie auf dem Laufenden – immer.
• Stellen Sie dann sicher, dass die Leute es sehen und verwenden.