Wie viel Code-Dokumentation sollte ein effektives Scrum-Team erstellen?

Darauf kann es keine allgemeingültige Antwort geben. Multinationale oder öffentliche Unternehmen sind sehr unterschiedlich. Software, die von solchen Unternehmen entwickelt wird, variiert noch mehr in Größe, Typ, Zweck, Verwendung, Lebenserwartung usw. Im Allgemeinen gilt: Je größer, länger verwendet und gewartet, komplexer die Software ist und desto mehr Menschen (gleichzeitig und /oder langfristig), und je regulierter die Domain ist, desto mehr Dokumentation erfordert sie.

Der neue Scrum Master sträubte sich gegen jegliche Dokumentation

... was mir etwas übereifrig klingt. Alle diese Personen können höchstwahrscheinlich die relevanten Teile des Agilen Manifests auswendig zitieren:

[...] schätzen wir: Funktionierende Software über umfassende Dokumentation [...]

Sie vergessen jedoch oft, dies zu zitieren:

Das heißt, während die Elemente auf der rechten Seite einen Wert haben, schätzen wir die Elemente auf der linken Seite mehr.

Du sagst

Wir scheinen uns darauf geeinigt zu haben, jeden Aspekt zu dokumentieren, der das Risiko birgt, die Abhängigkeit einer anderen Abteilung zu beeinträchtigen.

(Kurz gesagt – wenn sie etwas kaputt machen, das ihnen nicht gehört, haben sie eine Dokumentation, um den Prozess, die Absicht und die Argumentation zu untermauern).

was für mich nach einem pragmatischen Ansatz klingt, dem ich auch folgen würde. Es hat in der Tat keinen Wert, Dokumentation nur um der Sache willen zu erstellen, aber immer wenn Stakeholder eine Dokumentation anfordern und/oder ein Problem identifiziert wird, das auf eine unzureichende oder veraltete Dokumentation zurückzuführen ist, muss das Scrum-Team sich darum kümmern. Natürlich ist ein persönliches Gespräch auf vielen Ebenen effektiver als eine schriftliche Dokumentation; es hält jedoch nur so lange wie das Gedächtnis der Teilnehmer und ist in manchen Fällen (z. B. verteilte Teams) nicht durchführbar. Wann immer wir dauerhaftere und/oder übertragbarere Spuren von Dingen brauchen, müssen wir sie dokumentieren.

Die primäre Widerlegung gegen eine eingehende Dokumentation war dies

• Es muss als User Story berücksichtigt und mit einem Punktewert versehen werden (was ich akzeptiere)
• Es ruiniert den Fluss der Entwicklerarbeit (auch akzeptiert)

Nun, man kann auch sagen, dass das Testen den Arbeitsfluss der Entwickler ruiniert. Sowie Mittagspausen ;-P

Beachten Sie, dass alles, woran man nicht gewöhnt ist, tatsächlich dazu neigt, den Fluss zu unterbrechen. Sobald wir uns daran gewöhnt und Erfahrungen gesammelt haben, wird es Teil des Flusses werden.

• Die Dokumentation ist innerhalb einer Woche aufgrund von Codeänderungen/Verbesserungen usw. veraltet (was ich nicht vollständig akzeptiere)

Es ist in der Tat ein Risiko, aber es hängt ganz davon ab, was dokumentiert wird. Dokumentieren Sie nicht die Details des Codes auf niedriger Ebene, die sich bis nächste Woche ändern können, sondern die Aspekte auf höherer Ebene - Architektur, Designentscheidungen, verwendete Muster, Schnittstellen usw. -, die sich nicht so oft ändern und / oder nicht direkt vorhanden sind innerhalb des Codes, sondern sind entscheidend, damit sich zB ein Außenstehender oder ein neues Teammitglied schnell einen Gesamtüberblick über das System verschaffen kann.

• Die Dokumentation ist im Code enthalten (was ich geradewegs als schlechteste Praxis abgelehnt habe)

Kommt darauf an, was das bedeutet. Wenn dies bedeutet, dass Dokumentation aus Codekommentaren wie Javadoc automatisch generiert wird, ist dies in Ordnung, obwohl es meiner Erfahrung nach meistens von begrenztem Nutzen ist (außer für öffentliche Schnittstellen). Wenn es bedeutet, erklärende Kommentare in den Code einzubetten, ist es meiner Meinung nach fast immer eine schlechte Idee (außer in seltenen und begrenzten Fällen wie der Implementierung eines bestimmten Algorithmus oder Änderungen der Leistungsoptimierung). Wenn es bedeutet, lesbaren, selbsterklärenden, flüssigen Code zu schreiben, stimme ich voll und ganz zu. IMHO gut geschriebener, sauberer Code braucht selten Kommentare.

Also, um es mit ein paar Faustregeln zusammenzufassen:

• Sprechen Sie mit Ihrem PO, Stakeholdern und dem Scrum-Team, um herauszufinden, wer welche Art von Dokumentation benötigt und warum (und ob ihr Grund gut genug ist).
• (z. B. bei Reviews und Retrospektiven) Identifizieren Sie Probleme, die durch fehlende oder unzureichende Dokumentation verursacht werden.
• Wenn es einen berechtigten Bedarf gibt, tun Sie die minimal notwendige Arbeit, um diesen Bedarf zu erfüllen. (Unter Berücksichtigung der erwarteten Lebensdauer des Bedarfs / der Artefakte - Sie möchten möglicherweise langfristig optimieren, nicht kurzfristig. Beispielsweise ist das Schreiben eines Skripts zum automatischen Generieren eines Dokuments aus Konfigurationsdateien offensichtlich kostspieliger als das einmalige manuelle Kopieren, aber wenn Dieses Dokument muss in den nächsten 5+ Jahren jede Woche aktualisiert werden, das Skript wird sich schnell bezahlt machen.)
• Versuchen Sie immer, doppelte Informationen so weit wie möglich zu vermeiden. Im Idealfall hat jede Information eine einzige Quelle. Wenn also eine Aktualisierung erforderlich ist, können Sie dies einmal an der Quelle tun. Es muss möglicherweise an andere Stellen repliziert / kopiert werden, aber bemühen Sie sich, dies durch Automatisierung statt durch manuelle Arbeit zu lösen.
• Wenn (und so viel wie) Sie Dokumentation erstellen, bemühen Sie sich , diese im zugänglichsten und am einfachsten zu pflegenden Format zu erstellen (es sei denn, sie ist vertraulich). Meiner Erfahrung nach bedeutet dies ein Wiki wie Confluence, das Sie erwähnt haben. Es kann Word-Dokumente importieren, es speichert einen Verlauf aller Änderungen und es kann sogar mithilfe von Skripten automatisch aktualisiert werden.
• Suchen Sie außerdem – wenn sich Prozesse und Anforderungen ändern – nach veralteter, nicht mehr verwendeter Dokumentation , und beseitigen Sie sie, wenn Sie solche Dinge finden.

Nun, die Antwort ist wirklich "Es kommt darauf an" gemischt mit "Warum brauchen sie es?" und "Was ist das Mindeste, womit Sie davonkommen können?"

Hier geht es wirklich darum, Ihre Stakeholder zu interviewen und eine 5-Warum-Analyse durchzuführen. Finden Sie heraus, warum sie etwas brauchen, damit Sie dann daran arbeiten können, dieses Bedürfnis mit minimalem Aufwand Ihrerseits zu erfüllen, oder sogar gar nicht, weil es nicht zutrifft.

Früher war ich der PMO-Leiter für eine agile Gruppe in einem riesigen Wasserfall-, Six-Sigma- und Qualitätskontrolle-getriebenen Unternehmen. Wir mussten in der Lage sein, Hardwareprodukte oft in nur drei Monaten auf den Markt zu bringen. Das Mutterschiff brauchte zwei bis drei Jahre, um ein Produkt herauszubringen. Während das Hauptunternehmen diese 2-3 Jahre benötigte, nahmen wir ihre fertigen Produkte und fügten sie in unser Produkt ein, sodass wir alle fertigen Komponenten verwendeten, denen wir dann Software hinzufügten.

Der Wasserfall-/Qualitätsprozess des Hauptunternehmens hat unsere Projekte um Monate verlängert. Da uns das Qualitätsteam vom Versand abhalten könnte, konnten wir den Prozess nicht ignorieren.

Ich habe Stakeholder-Interviews mit allen Organisationen geplant, die wir berührt haben. Ich fand heraus, was sie brauchten und warum sie es brauchten. Indem ich nach dem Warum forschte, konnte ich oft sehen, dass es wirklich nicht auf uns zutraf. Es war nur ein Prozess, der so tief verwurzelt war, dass niemand ihn in Frage stellte. Ich konnte dann erklären, wie unsere Projekte funktionierten und warum wir diese Anforderungen nicht erfüllen mussten.

In den Fällen, in denen wir einige Unternehmensanforderungen erfüllen mussten, ließ uns die Warum-Analyse erkennen, was wir mindestens tun mussten, um sie zu erfüllen.

Oh, und in einigen Fällen hat uns die Warum-Analyse gezeigt, dass wir so sehr dachten, wir seien etwas Besonderes, dass wir es wirklich nicht waren. Manchmal musste unser Team es aufsaugen und erkennen, dass wir all diese Arbeit erledigen mussten, weil es wirklich nötig war.