Designdokumente als Teil von Agile

25

An meinem Arbeitsplatz stehen wir vor der Herausforderung, dass "agil" zu oft "vage Anforderungen, schlechte Akzeptanzkriterien, viel Glück" bedeutet! Wir versuchen, dies als allgemeine Verbesserungsmaßnahme anzugehen.

Als Teil davon schlage ich vor, dass wir Designdokumente generieren, die über die User Story-Ebene hinaus das Ergebnis vorläufiger Untersuchungen der Auswirkung eines bestimmten Features innerhalb des Systems genau widerspiegeln und Antworten auf Fragen enthalten, die wir haben fragte das Geschäft.

Gibt es dafür einen wirksamen Standard?

Wir sind derzeit mit einer Situation konfrontiert, in der sich ein neues Feature auf mehrere Bereiche unseres "Big Ball of Mud" -Systems auswirken kann, und die Schätzungen beginnen aufgrund dieser technischen Verschuldung zu steigen. Hoffentlich können durchdachte Designprozesse helfen.

asthasr
quelle
4
Die Lösung von agile ist die Kommunikation. Die Verantwortlichen, die wissen, WAS ist, sollten Entwicklern immer für Konsultationen zur Verfügung stehen. Außerdem sollten Sie Unit-Tests und häufiges Refactoring durchführen lassen, um den "großen Schlammballen" in Schach zu halten.
Euphoric
3
Ich weiß, dass wir diese Dinge haben sollten . Wir nicht Ich versuche, uns dabei zu helfen, dorthin zu gelangen, und ich versuche, einen zuverlässigen, wiederholbaren Rahmen für die Kommunikation zu schaffen (Dokumente sind schließlich Kommunikation). Das Problem ist, dass wir uns gerade auf das Thema "Jetzt erledigen!" Einlassen. Wir verlassen uns auf Ad-hoc-Kommunikation, die dazu führt, dass Menschen Wissenssilos haben, da es keinen Bezug zu den tatsächlichen Informationen über eine Funktion gibt, die nach der User Story entsteht.
Asthasr
4
Agile ist nicht gegen Dokumentation - es ist gegen nutzlose Dokumentation. Schreiben Sie so viel Dokumentation, wie Sie brauchen, und nicht mehr. Denken Sie insbesondere daran, dass die Dokumentation nur einen Verweis auf das mentale Modell darstellt, das Sie (das Team) in Ihrem Kopf haben. Letzteres ist das wirklich Wichtige - man kann es jedoch nie vollständig dokumentieren. Halten Sie es stattdessen über viele Kommunikationswege synchron, und notieren Sie sich nur genügend Referenzen, um sicherzustellen, dass das Modell langfristig konsistent bleibt.
Péter Török
Ich denke, du solltest eine andere Frage stellen als diese. Für diese Art von Frage erhalten Sie die allgemeine Meldung "Dokumente sind in Ordnung, wenn ...", die Ihnen nicht viel hilft. Sie sollten sich erkundigen, ob Ihre Lösung für Ihr Problem richtig ist, und nach anderen möglichen Lösungen fragen.
Euphoric
4
"Agil ist nicht gegen Dokumentation - es ist gegen nutzlose Dokumentation.": Jeder Entwicklungsprozess ist gegen nutzlose Dokumentation (gemäß ihrer Definition von nützlich und nutzlos).
Giorgio

Antworten:

18

"vage Anforderungen, schlechte Annahmekriterien, viel Glück!"

yup, das ist die gleiche Art von Anforderungen, die Sie erhalten, auch wenn Sie versuchen, sie auch festzunageln! (Beispielsweise war ein Dokument mit 10.000 Anforderungen, für dessen Erstellung ein Regierungskunde 4 Jahre benötigt hat, immer noch voller Inkonsistenzen, Ungenauigkeiten und sogar intern widersprüchlicher Aussagen. Wenn Sie mit einer Dokumentation mit 4 Jahren Anforderungen keine anständige, genaue Anforderung erhalten, tun Sie dies.) Hast du jemals gedacht, dass du irgendetwas bekommen kannst, das nicht vage ist?)

Also ... der agile Weg wurde erfunden, um zu verstehen, dass dies passiert, und um damit zu arbeiten, anstatt zu versuchen, dagegen zu arbeiten.

Sie beginnen mit der Frage "Was möchten Sie" und der Kunde antwortet mit "so etwas in der Art". Sie erledigen einige Arbeiten und kehren dann zum Kunden zurück und sagen: "Ist das so, wie Sie es wollten?". Der Kunde sagt normalerweise "Ja, aber ...", woraufhin Sie fragen: "Was möchten Sie".

Schließlich bekommen Sie genau das, was der Kunde wollte, auch wenn er nicht weiß, was das ist! (Hölle, sie wissen nie , was sie wollen, nicht genau).

gbjbaanb
quelle
Interessant ist die Anekdote des Regierungsentwurfs, gibt es eine Quelle? Oder einfach etwas, das Sie selbst erlebt haben?
user145400
@ user145400 etwas, das ich erlebt habe :-(
gbjbaanb
13

Seit wir agil sind, haben wir in unserem Team auch versucht, die tatsächlich erforderliche Dokumentation einzugrenzen und zu verstehen. Ich kann mit Ihnen teilen, was wir bisher gelernt haben.

Lesen Sie vor allem diesen Artikel über die Agile / Lean-Dokumentation . Sehr gut zu lesen.

Zweitens rate ich Ihnen dringend, die Erstellung von Designdokumenten nach den Vorarbeiten für Geschichten zu überdenken. Wir haben das schon einmal versucht und es hat sich als Verschwendung erwiesen. In der Mitte der letzten Version haben wir uns entschlossen, die Designdokumente NUR NACH Lieferung des Codes für die Story zu aktualisieren. Und jetzt denke ich sogar, dass das zu früh ist.

Sie müssen sich fragen, warum Sie vor dem Codieren Dokumente entwerfen möchten. Für uns waren das die Gründe:

  1. Wir als Team müssen verstehen, wie sich die Geschichte auf das Design auswirkt.
  2. Das Vorhandensein von Designdokumenten hat sich als nützlich erwiesen, wenn neue (oder vorübergehende) Mitglieder dem Team beitreten oder zu Code zurückkehren, an dem seit über einem Jahr niemand mehr gearbeitet hat. Sie sind daher hilfreich für das organisatorische Gedächtnis, um zu verstehen, wie der Code funktioniert.
  3. Konstruktionsdokumente sind hilfreich für Wartungstechniker, die nach der Veröffentlichung möglicherweise Fehler im Code beheben müssen.

Um (1) zu erfüllen, müssen Sie kein tatsächliches Designdokument erstellen. Ihr Team sollte vor dem Codieren noch eine Designphase haben, aber diese Phase kann so einfach wie eine 15-minütige Sitzung vor einem Whiteboard oder einer Serviette sein. Sie müssen kein tatsächliches Dokument erstellen, dessen Erstellung Stunden (wenn nicht Tage) in Anspruch nimmt, um die Designänderungen zu besprechen.

(2) oder (3) werden während der Entwicklung der aktuellen Story nicht benötigt und werden höchstwahrscheinlich nicht für mehrere nachfolgende Iterationen benötigt.

Denken Sie auch daran, dass jedes Mal, wenn ein Teammitglied Konstruktionsdokumente schreibt / aktualisiert, der Code nicht geschrieben wird. Wenn Sie Dokumente vor dem eigentlichen Code schreiben, besteht eine fast hundertprozentige Wahrscheinlichkeit, dass sie aktualisiert werden müssen, da das Design nach dem Start der Codierung immer wieder geändert wird. Und selbst wenn Sie nach dem Code Designdokumente schreiben, wie unser Team erfahren hat, ändert das Umgestalten aus nachfolgenden Geschichten das Design.

Also was würde ich empfehlen:

  1. Produzieren Sie zunächst genügend temporäre Designs / Modelle, damit Ihr Team vor dem Codieren ein intelligentes Gespräch führen kann. Erwarten Sie nicht, diese zu behalten, und verschwenden Sie keine Zeit damit, sie zu formalisieren.
  2. Erstellen Sie offizielle Konstruktionsunterlagen nur, wenn jemand sie benötigt (dh Ihr Team hat einen echten Bedarf an organisatorischem Gedächtnis).
  3. Erstellen Sie die Konstruktionsdokumentation nur mit stabilisiertem Code. Es macht keinen Sinn, ein Modul zu dokumentieren, das in jeder Iteration geändert wird.
  4. Erstellen Sie Konstruktionsdokumente, die ein Modul (oder einen Teil des Produkts) vollständig beschreiben. In der Vergangenheit haben wir Design-Dokumente geschrieben, in denen die Änderungen dokumentiert sind, die vorgenommen werden müssen. Diese Dokumente waren völlig wertlos, sobald die Veröffentlichung abgeschlossen war.
  5. Halten Sie das Dokument sehr hoch. Wenn Sie 20 Seiten schreiben, die sich mit Architektur und sehr anspruchsvollem Design befassen, wird dieses Dokument a) tatsächlich von anderen Personen gelesen und b) den Leuten dabei geholfen, sich mit dem allgemeinen Layout Ihres Codes vertraut zu machen. Für Details können die Leute direkt in den Code gehen. Wenn Sie 700 Seiten mit detaillierten Spezifikationen schreiben, stimmen diese fast immer nicht mit der Realität überein. Es ist zu viel für jedermann, sie zu lesen, und Sie müssen 700 statt 20 Seiten warten und aktualisieren, wenn zukünftige Änderungen vorgenommen werden.
DXM
quelle
Was du sagst, scheint ähnlich zu sein, zu dem ich zu gelangen versuche; Wir haben einen komplexen Schlammball, und ich möchte einfache Dokumente, die a) die Geschäftsabsicht eines bestimmten Features (dh ausgearbeitete User Stories mit beantworteten Fragen) kommunizieren; b) darauf hinweisen, welche Teile des Codes und der vorhandenen APIs betroffen sind; und c) als einmalige Artefakte behandelt werden und nicht für immer mit jedem neuen Feature aktualisiert werden müssen. Es ist interessant für mich, 20 Seiten als "hoch" zu bezeichnen - auch das fehlt uns. :)
Asthasr
@syrion: Basierend auf dem, was Sie gerade gesagt haben, klingt es so, als ob Sie jede einzelne Story detailliert dokumentieren und ein Dokument mit einer "Designlücke" erstellen möchten (dh den Unterschied zwischen dem, was heute im Code enthalten ist, und dem, was einmal im Code enthalten sein wird) Geschichte ist geschafft). Haben Sie ein Publikum für solche Dokumente? Aus meiner Erfahrung gehe ich davon aus, dass niemand sie tatsächlich lesen wird. Entwickler, die heute an der Story arbeiten, wissen bereits, was geändert werden muss (sie haben das Dokument entweder geschrieben oder waren Teil der anfänglichen Diskussion). Und wenn Sie versuchen, ALLE Details der Änderungen zu erfassen, die Sie in einer Story vornehmen werden, ...
DXM
... Sie verbringen mehr Zeit mit dem Verfassen von Dokumentationen als mit dem eigentlichen Codieren. Und wenn die Geschichte fertig ist, wie Sie gesagt haben, handelt es sich um einmalige Artefakte. Warum müssen sie dann überhaupt produziert werden?
DXM
weil wir im Moment eine Umgebung voller Wissenssilos haben. Wir haben Leute, die das Subsystem A kennen, weil sie es geschrieben haben, und B, weil sie geholfen haben, es zu unterstützen, als es das letzte Mal explodierte, aber C nie berührt hat, und D wurde seitdem umgeschrieben. Es ist schwierig für Neulinge und externe Auftragnehmer, sich auf dem Laufenden zu halten.
Asthasr
@syrion: es hört sich wirklich so an, als hättest du das gleiche Bedürfnis wie wir. Ich bin jedoch verwirrt, als Sie sagten, Sie möchten einfache Dokumente, die ... als einmalige Artefakte behandelt werden. Nehmen wir also an, Sie haben eine Ebene, die mit der Datenbank spricht, und 6 Geschichten, die Änderungen an dieser Ebene erfordern. Planen Sie, zu jeder Geschichte 6 verschiedene Dokumente zu erstellen? Oder möchten Sie eine einzige Designspezifikation für den DB-Layer haben? Eine einzelne Spezifikation muss jedoch mit jedem Feature aktualisiert werden, das die DB-Ebene berührt.
DXM
3

Das agile "Mantra" kommt nicht ganz ohne Dokumentation aus.

Das Agile-Mantra lautet: " Arbeitssoftware gegenüber umfassender Dokumentation ". Beachten Sie jedoch den unteren Teil des Manifests.

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

Onkel Bob hat eine gute Richtlinie für die Dokumentation

Produzieren Sie kein Dokument, es sei denn, es ist unmittelbar und wichtig .

Sie haben Recht, dass manche Leute Agile als Entschuldigung dafür benutzen, keine Dokumentation zu erstellen, aber das ist schlecht, Agile. Es ignoriert die Stellen, die ich in den obigen Zitaten hervorgehoben habe.

Wenn Sie jedoch sagen, dass wir derzeit mit einer Situation konfrontiert sind, in der sich eine neue Funktion auf mehrere Bereiche in unserem "Big Ball of Mud" -System auswirken kann, müssen Sie etwas dagegen tun, wenn Sie agil sein möchten.

Wenn Sie Ihre Dokumentation haben, können Sie damit Ihren Code modularisieren. Auf diese Weise beseitigen Sie die langfristige Notwendigkeit, die Dokumentation zu pflegen (was nicht der Fall ist), indem Sie die langfristige Notwendigkeit für die Dokumentation beseitigen.

dh Machen Sie den Bedarf sofort und bedeutend.

pdr
quelle
Diese Antwort ist "richtig", denkt aber nicht wirklich darüber hinaus. Was ist zum Beispiel mit einem Architekturdesign? Was ist mit dem Umsatz von Entwicklern / Unternehmen? Wie wird das bei vielen Qualitäts-Unit-Tests gehandhabt?
Paul
@Paul: Es ist eine gute Idee, SEHR hochwertige Architekturdiagramme zusammen mit sehr leichten Codierungsstandards für Neulinge zu haben. Ich habe festgestellt, dass ein guter Weg, um diese Dokumente auf dem neuesten Stand zu halten, darin besteht, sie in einem Wiki zu halten und jeden Neuling dazu zu bringen, dort zu aktualisieren, wo er sie als datiert ansieht. Bei dieser Frage ging es jedoch speziell um vordefinierte Designdokumente.
pdr
Ich stehe immer noch zu dem, was ich sage. Ändern Sie die Architektur so, wie das Unternehmen es nennen möchte, und ändern Sie die Komponententests in Regressionstests (automatisiert?).
Paul
@Paul: Entschuldigung, ich verfolge nicht. Welches wertvolle Dokument finde ich schlecht?
pdr
0

Das Agile ist, dass die Dokumentationsbemühungen wirklich vom Scrum-Team vorangetrieben werden müssen. Wenn die Entwickler der Meinung sind, dass externe Dokumentation nicht für ihre Anforderungen ausreicht, wird die User Story blockiert, bis sie dies tun. Wenn das Unternehmen der Ansicht ist, dass Entwickler keine ausreichende Dokumentation erstellen, besteht der Product Owner darauf, diese zu einem Teil der Akzeptanzkriterien zu machen. Aus diesem Grund habe ich festgestellt, dass unsere Dokumentation fokussierter und effektiver ist, seit ich zu Scrum gewechselt bin.

Wir verwenden VersionOne , um unsere User Storys zu verfolgen, aber ich bin mir sicher, dass unsere Methoden auch auf andere Systeme anwendbar sind. Damit können Sie Dateien an User Stories anhängen. Wir haben festgestellt, dass dies ein äußerst nützlicher Ort ist, um Konstruktionsdokumente abzulegen.

Für ein Beispiel, das für uns sehr gut funktioniert hat, mussten wir so schnell wie möglich nach dem Bau des Prototyps ein neues Leiterplattendesign testen. Wir haben zwei User Stories für alles erstellt, was getestet werden musste: eine zum Entwerfen des Tests und eine zum Ausführen des Tests. Ein Akzeptanzkriterium für die Designgeschichte war, dass der Testvorgang vollständig in der Ausführungsgeschichte dokumentiert war.

Als wir zum Testteil kamen, lief es reibungsloser als je zuvor. Wir haben gerade die User Story geöffnet und das schrittweise Vorgehen befolgt. Die Dokumentation war genau das, was wir brauchten, um die Geschichte zu vervollständigen, nicht mehr und nicht weniger.

Wir haben eine andere Geschichte in unserem Backlog, nur um die Dokumentation für einen von uns verwendeten Chip zu verbessern, damit andere Teams ihn leichter für ihre eigenen Produkte abholen können.

Zusammenfassend lässt sich sagen, dass die Lösung, wenn Sie das Gefühl haben, dass Ihre Dokumentation darunter leidet, so einfach ist, wie eine separate User Story zu erstellen und / oder sie zu einem Teil der Akzeptanzkriterien zu machen.

Karl Bielefeldt
quelle
0

Wenn Sie von schlechten Anforderungen sprechen, fällt mir als Erstes ein, ob Sie die Testkriterien haben. Erstellen Sie nach Möglichkeit wiederverwendbare automatisierte Testfälle für vorhandene Teile des Systems. Sobald alle damit vertraut sind, schreiben Sie die Testfälle, bevor der Code geschrieben wird. Gute Testfälle können viel dazu beitragen, das Verhalten eines Systems zu dokumentieren.

Welche spezifischen Designdokumente verwendet werden sollen, hängt, wie bereits gesagt, stark von den Anforderungen des Teams ab und von der nächsten Aufgabe, die sie übernehmen werden. Versuchen Sie nach Möglichkeit, Tools zu verwenden, mit denen Sie die Dokumente (aus dem verwendeten Code) oder den Code aus dem Dokument generieren können. Die Pflege der Dokumentation kann sehr kostspielig werden. Wählen Sie also mit Bedacht aus, wenn Sie ein Designdokument beibehalten möchten.

Persönlich hatte ich gute Erfolge mit Klassendiagrammen, die aus Code- und Fitnesstestfällen generiert wurden. Das Team druckt ein paar Klassendiagramme aus, führt eine Markierungssitzung mit dem Produktbesitzer durch und formuliert dann eine Schätzung von dort. Was Fitness angeht, habe ich das Glück, mit einigen Produktbesitzern zusammenzuarbeiten, die sehr gut darin sind, ihre Wünsche in Tabellenkalkulationen auszudrücken, die dann in Tabellen für Fitness umgewandelt werden.

Abstrakte Klasse
quelle