Was ist ein effektiver Weg, um Gründe für Produktdesignentscheidungen aufzuzeichnen?

30

In unserem Unternehmen verwenden wir keine Produktdesign-Dokumente. Wir haben insgesamt drei Mitarbeiter, sodass alle Produktdesign-Diskussionen persönlich oder über Slack stattfinden. (Wir haben auch das grundlegende Slack-Paket, mit dem nur die neuesten Nachrichten angezeigt werden können.)

Unser Produkt befindet sich noch in einem frühen Stadium und wir greifen häufig Designelemente auf, die vor Monaten festgelegt wurden.

Ein Problem, mit dem wir in äußerst häufigen Fällen konfrontiert sind, besteht darin, zu vergessen, warum eine Entscheidung zum Produktdesign getroffen wurde. Dies führt zu stundenlanger Runderneuerung auf demselben Untergrund.

Wie können wir die Hintergründe für Designentscheidungen effektiv aufzeichnen?

Unser Workflow basiert auf Pivotal Tracker. Eine Lösung, die mir einfällt, besteht darin, die Gründe für alle relevanten Entwurfsentscheidungen als Kommentare zur User Story selbst aufzuzeichnen, was jedoch unzuverlässig erscheint.

Um 100% klar zu sein: Ich spreche nicht über das Design von Code. Ich spreche über das Design des Produkts, das durch den Code realisiert wird. Mit anderen Worten, ich spreche nicht von Entscheidungen wie "Sollen wir diese Klasse eher mit Komposition als mit Mehrfachvererbung strukturieren?"; Ich spreche von Entscheidungen wie "Soll ein Benutzer seine E-Mail-Adresse bestätigen, bevor er sich anmelden kann?".

Der Zweck der Dokumentation besteht darin, dem Unternehmen die Möglichkeit zu geben, Aufzeichnungen darüber zu erhalten, warum Entscheidungen getroffen wurden, um weitere Entscheidungen zu denselben Themen zu treffen.

Henrebotha
quelle
13
Wenn Sie das Gefühl haben, eine Form eines Designdokuments zu benötigen, warum nicht einfach ein Designdokument erstellen?
MetaFight
Ich nehme an, die Rationales werden als Prosa aufgezeichnet, schriftliche Prosa auf den ersten Blick. Wer ist der dafür vorgesehene Leser?
Laurent LA RIZZA
Warum ist es Ihrer Meinung nach unzuverlässig, dies in den User Stories auf Pivotal festzuhalten? Ich habe diese Software noch nie benutzt, aber normalerweise ist ein Ticket ein guter Ort, um die Motivation für das Erheben des Tickets aufzuzeichnen. Geben Sie nicht einfach "Benutzer zur Bestätigung der E-Mail-Adresse auffordern" ein, sondern "Benutzer zur Bestätigung der E-Mail-Adresse auffordern". Dies hilft, weil ... "Sie sagen, dass dies unzuverlässig ist, weil Sie es möglicherweise nicht tun (dh Sie möchten einen Prozess, der dies erzwingt) Sie tun das Richtige) oder sind unzuverlässig, weil alte Pivotal-Geschichten in einem schwarzen Loch verschwinden und Sie sie nicht finden, oder gibt es ein anderes Problem?
Steve Jessop
Wer sind die Autoren und wer sind die Verbraucher dieser Dokumentation? Es klingt für mich so, als ob "das Geschäft" der Autor ist und jeder Leser davon ist? Wäre das richtig? (Ich verstehe, dass Sie gerade klein sind, aber wenn Sie wachsen würden, was wären die Antworten?)
mlk
Ich würde vorschlagen, dass ein Benutzer seine E-Mail-Adresse bestätigen muss, bevor er sich anmelden kann. Art von Entscheidungen sollte unter Akzeptanzkriterien gehen.
Kumards

Antworten:

26

Sie erfassen die Gründe für Entwurfsentscheidungen, indem Sie sie aufschreiben. Idealerweise in der Nähe des Gegenstandes, der der Entscheidung unterliegt (bei dem es sich nicht um eine "User Story" handelt - User Storys sind Beschreibungen, was implementiert werden muss, nicht wie).

Dies ist insbesondere der Grund, warum Kommentare gemacht werden, um aufzuzeichnen, warum ein bestimmtes Stück Code oder eine bestimmte Struktur so aussieht (und ich spreche nicht ausschließlich von Codekommentaren). Wenn das Thema Ihres Entwurfs eine Funktion ist, machen Sie einen einleitenden Kommentar zu der Funktion. Wenn es sich um eine Klasse handelt, machen Sie am Anfang einer Klasse einen Kommentar zu der Begründung. Wenn Sie eine Reihe von Klassen haben, die alle der gleichen Struktur folgen sollen, fügen Sie dem Paket, das diese Klassen enthält, ein separates Designdokument (wie eine "Readme" -Datei) hinzu. Wenn das Thema Ihres Entwurfs ein UML-Diagramm ist, fügen Sie dem Beschreibungsabschnitt des Diagramms Kommentare hinzu.

IMHO-Designdokumente mögen ihren Wert haben, aber wenn sie Dinge beschreiben, die zu weit von dem Gegenstand entfernt sind, den sie beschreiben, neigen sie dazu, sehr schnell inkonsistent zu werden. Daher empfehle ich, jegliche Konstruktionsunterlagen so nahe wie möglich an dem entworfenen Gegenstand anzubringen.

Verwenden Sie separate Dokumente nur, wenn Sie Entwurfsentscheidungen dokumentieren möchten, die sich übergreifend auf viele verschiedene Stellen Ihres Codes auswirken. Wenn Sie sie verwenden, versuchen Sie, sie zu einem Teil Ihrer Codebasis zu machen, und platzieren Sie sie auf der entsprechenden Hierarchieebene des entworfenen Themas. Wenn Sie also eine Entwurfsentscheidung für ein Modul treffen, das aus mehreren Quellcodedateien besteht, platzieren Sie die Entwurfsbeschreibung. in "diesem Modul, aber nicht in einer Klassendatei, nicht in einer" Top-Level-Beschreibung ", die für andere Module gültig ist, und definitiv nicht in einem separaten Wiki außerhalb Ihres SCCS. Wenn Sie ein" High-Level "-Produkt aufnehmen möchten breite Entwurfsentscheidungen, dann ist ein Dokument der obersten Ebene vielleicht der beste Ort, aber stellen Sie sicher, dass dieses Dokument auf dieser Abstraktionsebene bleibt.

Doc Brown
quelle
Zu Kommentaren: Würden Sie nicht sagen, dass der Zweck von Kommentaren darin besteht, Code zu beschreiben? Weil die Art von Problem, über das ich spreche, Designprobleme sind, wie: Sollte der Benutzer X-Berechtigungen haben, wenn er Y-Kontoeinstellungen hat? Der Zweck von Code ist es, das Design zu aktivieren, daher glaube ich nicht, dass der Code der geeignete Ort ist, um das Design zu diskutieren.
Henrebotha
5
@henrebotha: Sie scheinen eine andere Vorstellung zu haben als ich, was Design ist, sein kann oder sein sollte. Code ist Design. Die Struktur des Codes ist Design. Die Struktur der Benutzeroberflächen ist Design. Metastrukturen von Code oder Klassen sind Design. Eine Frage wie "Sollte der Benutzer X-Berechtigungen mit Y-Kontoeinstellungen haben" klingt für mich nach etwas, das Sie nicht irgendwo in Ihre Software einbinden möchten - eher nach einer konfigurierbaren Anforderung. Wie Sie diese Anforderung in Code implementieren, kann eine Entwurfsentscheidung sein, sodass Sie sie irgendwo in Ihrem Code kommentieren können.
Doc Brown
2
@henrebotha: Wenn Sie die Berechtigungen X für die Kontoeinstellungen Y fest verdrahten, wirkt sich diese Entscheidung auf den Code aus. Ein Code, der die Berechtigungen steuert, ein Code, der die Kontoeinstellungen verwaltet, ein UI-Code und ein Controller-Code. An all diesen Stellen sollte sich also ein Kommentar im Code befinden. Natürlich, um Wiederholungen zu vermeiden, können sich alle Kommentare auf ein separates Designdokument beziehen, wenn dahinter eine Begründung steht, die viele verschiedene Stellen betrifft (wie ich in meiner Antwort sagte).
Doc Brown
1
Ich bestreite nicht, dass Designentscheidungen sich auf den Code auswirken. Natürlich beeinflussen Designentscheidungen den Code. Dies bedeutet jedoch nicht, dass Kommentare der richtige Ort sind, um Entscheidungen zum Produktdesign aufzuzeichnen.
Henrebotha
1
@henrebotha: Es hängt davon ab, was Sie unter "Produktdesignentscheidungen" verstehen. "Produktweite" Entwurfsentscheidungen können in ein Dokument auf der "obersten Ebene" Ihrer Produktdokumentation gehören. Wenn Sie irgendeine Art von "Entwurfsentscheidung in Ihrem Produkt" meinen, gehören einige davon in Codekommentare, andere nicht. Aber ich spreche nicht nur von Code-Kommentaren, siehe meine Bearbeitung. Ich spreche von jeder Form von Kommentaren (innerhalb von Code oder in separaten Dokumenten), die Sie zu einem Teil Ihrer Codebasis machen.
Doc Brown
8

Betrachten Sie einen agilen Ansatz. Ich meine, wenn Sie die Zeitressourcen und die hervorragenden Schreibfähigkeiten haben, um jede Designentscheidung aufzuschreiben, die Sie mit ihren Begründungen treffen, dokumentieren Sie einfach alles. Realistisch gesehen gehe ich davon aus, dass Sie nicht in einer solchen Position sind. Ein agiler Ansatz kann bei einer zentralen Herausforderung für die Dokumentation von Rationalen hilfreich sein: Oft wissen Sie erst später, welche Rationalen wichtig waren.

Gehen wir das Problem ganzheitlich an. Ihr habt Gründe für eure Entscheidung. Sie sind gerade in Squishyware gefangen, dem Gehirn des Teams. Trotz der Menge an Kreditdokumenten ist das Speichern von Rationalen in sqishyware gar nicht so schlecht. Wir sind als Spezies wirklich gut darin, uns an die wichtigen Dinge zu erinnern. Deshalb verfügt jedes große Unternehmen über "Stammeswissen", auch wenn diese Unternehmen versuchen, all dieses Stammeswissen zu dokumentieren.

Jetzt hast du ein Problem. Sie stellen fest, dass die sqiushyware nicht gut genug an den Begründungen festhält. Gut für Sie, wenn Sie feststellen, dass es ein Problem gibt und feststellen, dass es gelöst werden muss! Das ist nicht immer ein einfacher Schritt! Wir sind uns ziemlich sicher, dass die Lösung darin besteht, einige dieser Überlegungen in die Dokumentation zu verlagern. Das reicht jedoch nicht aus. Wir können niemals die zweite Hälfte des Puzzles vergessen, die darin besteht, das Grundprinzip in die Squishyware zu laden, wenn Sie eine Entscheidung treffen müssen. Ich habe viele Teams gesehen, die alles wie verrückt dokumentieren, aber der Inhalt ist eigentlich nicht so organisiert, dass er gute Entscheidungen ermöglicht. Deshalb vergessen sie Rationales , obwohl sie aufgeschrieben sind .

Sie haben also einen zweistufigen Prozess. Sie müssen die Gründe aus der Squishyware heraus und in die Dokumentation einfließen lassen. Dann müssen Sie sicherstellen, dass die Dokumentation gut genug organisiert ist, um das Rationale bei Bedarf wieder in Squishyware umzuwandeln! Jetzt haben wir meines Erachtens genug von einer Problemstellung, um zu erkennen, wo die Herausforderungen liegen werden. Wenn Sie dokumentieren, wissen Sie normalerweise nicht, wer es später ansehen wird oder wonach sie suchen. Wenn Sie auf die Dokumentation zurückblicken, wissen Sie in der Regel nicht, wonach Sie suchen (bestenfalls wissen Sie, wann).

Ein großes Unternehmen könnte versuchen, dies in zwei großen Blöcken zu handhaben. Erstens können sie Anforderungen entwickeln, die auf den Bedürfnissen der Benutzer bei der Recherche der Dokumentation basieren. Dann verwenden sie diese Anforderungen, um einen Prozess für die Entwicklung dieser Dokumentation zu erstellen. Und wenn ich es so sagen darf , dann beschwert sich jeder, denn fast niemand weiß genau, wie die Dokumentation am ersten Tag aussehen soll. Die Dokumentation ist immer unvollständig und die Entwickler beschweren sich immer, dass der Prozess zu aufwändig ist.

Zeit, agil zu werden.

Mein Rat wäre, agile Anstrengungen zu unternehmen, um Ihren Dokumentationsprozess zu verbessern: Die gesamten neun Meter von Squishyware über Dokumente bis hin zu Squishyware. Erkennen Sie im Voraus, dass Sie einige Informationen verlieren werden, weil Ihr Prozess nicht perfekt ist, aber das ist in Ordnung, weil Sie immer noch versuchen, den Prozess herauszufinden! Sie würden mehr vermissen, wenn Sie versuchen, eine Einheitsgröße zu schaffen.

Ein paar besondere Leckerbissen, die ich mir ansehen möchte: * Informelle Dokumentation durchsehen. Formale Dokumentation ist großartig, aber zeitaufwändig. Zu den Zwecken der Dokumentation gehört es, Informationen von Entwickler-Squishyware freizugeben und auf Papier zu bringen. Informelle Dokumentation reduziert die Kosten auf ein Minimum.

  • Akzeptieren Sie unzuverlässige Dokumentationsformate. Nichts wird beim ersten Mal richtig sein. Es ist besser, die Daten abzurufen und später herauszufinden, wie sie zuverlässig sind. Beispielsweise könnten Sie Ihre Begründungen in einem <rationale> </ rationale> Block oder einem ähnlichen Dokument dokumentieren, wodurch es einfacher wird, diese Daten später zu sammeln. Das Speichern der Rationales in einer User Story ist vorerst in Ordnung!
  • Vergessen Sie niemals den Wert der Organisation. Finden Sie heraus, wie Sie als Team nach Begründungen in der Dokumentation suchen und versuchen, diese zu dokumentieren. Jedes Team wird einen anderen Prozess haben. In einem meiner Teams konnten wir das Ticket, das die Gründe hatte, nicht sofort finden. Was wir tun könnten, ist, eine wichtige Codezeile svn blamezu finden, herauszufinden, wann sie geändert wurde und warum, und dann die Tickets anzusehen. Sobald wir dort waren, haben wir in der Regel alle Gründe, die wir brauchten, direkt auf das Ticket geschrieben. Das hat gerade bei uns geklappt, finde heraus, was bei dir funktioniert.
  • Organische Dokumentation kann im Laufe der Zeit wachsen. Es ist selten, dass Entwickler wissen, welche Überlegungen an dem Tag, an dem sie sie schreiben mussten, am wichtigsten sind. Wir finden normalerweise später heraus, welche wichtig waren. Wenn Sie einen Aufbereitungsprozess für die Dokumentation haben, der es den Entwicklern ermöglicht, ihren eigenen kleinen Garten von Begründungen zu verwalten, tauchen die wichtigen auf. Noch wichtiger ist, dass sich die Gründe ändern können. Sie werden vielleicht feststellen, dass zwei unterschiedliche Änderungen mit zwei unterschiedlichen Begründungen am besten durch eine einzige Begründung beschrieben werden können, die für beide gilt. Jetzt gibt es weniger Inhalt zwischen Ihnen und Entscheidungen!
Cort Ammon - Setzen Sie Monica wieder ein
quelle
0

Ich würde vorschlagen, eine private Instanz von MediaWiki oder einer ähnlichen Wiki-Software einzurichten. Es ist wirklich einfach, Inhalte dort zu organisieren und neu zu organisieren, und Sie können neue Diskussionen direkt in die Diskussionsregisterkarte der entsprechenden Wiki-Artikel kopieren und einfügen. Wir haben MediaWiki in meinem letzten Job für alle unsere Architektur- und API-Dokumente verwendet und es war ein Lebensretter.

Nullbandbreite
quelle
2
Architektur & hochrangige Entscheidungen - könnten in Ordnung sein. API-Dokumente - NEIN! Einige Mitarbeiter unserer Organisation haben dies in der Vergangenheit versucht und es ist immer dasselbe - Dokumente auf niedriger Ebene sind nicht mehr mit dem Code synchron. Wikis interagieren nicht gut mit dem VCS, die Leute vergessen oder nehmen sich nicht die Zeit, es zu aktualisieren usw. API-Dokumente gehören in den Code , vor die von ihnen beschriebenen Funktionen. Wenn Sie der Meinung sind, dass Sie sie in Ihrem Intranet benötigen, verwenden Sie einen HTML-Generator wie doxygen, um sie von dort zu extrahieren. Aber tun Sie sich selbst einen Gefallen und pflegen Sie sie nicht einzeln, manuell, in einem Wiki.
Doc Brown
3
Ich bin der festen Überzeugung, dass alle Design-Rationales im Quellcode-Repository niedergeschrieben werden sollten. An jedem anderen Ort geraten sie nicht nur aus dem Takt, sondern erinnern sich auch nicht an ihre Geschichte.
cmaster
Downvoting eine Lösung, die funktioniert ... Wow. OK dann.
zerobandwidth
0

Denken Sie darüber nach aus der Sicht des Programmierers, der gebeten wird, es in 12 Monaten zu ändern.

Wenn Sie diese Geschäftsregel als automatisierten Test hinzufügen, wird die Änderung vorgenommen UND DANN erhalten Sie durch den fehlgeschlagenen Test die widersprüchliche Anforderung (und hoffentlich erfassen Sie die Person, die der ursprünglichen Anforderung zugeordnet ist, und deren Grund für die Angabe).

Ich betrachte das Designdokument (den Ort, an dem Sie Ihre BPMN-Diagramme, Transaktionsdiagramme, sogar ein Foto des Whiteboards usw. ablegen) als dem Code ähnlich, nur als nicht ausführbare Form ... was bedeutet, was Sie versuchen record ähnelt einem Codekommentar, ist jedoch eine (testbare) Anforderung, die im Entwurf im Voraus festgelegt wurde. Vermutlich, wenn Sie ein agiler Shop sind, entwerfen Sie Ihren Code immer noch, Sie tun es in letzter Minute, bevor Sie ihn schreiben. Behalten Sie dies in der Codebasis mit allen anderen Projektdokumenten.

Stellen Sie auf jeden Fall sicher, dass sie durchsuchbar gespeichert sind (z. B. möchten Sie möglicherweise alle Geschäftsregeln für die "Authentifizierung" aufrufen, wenn Sie neue Änderungen festlegen).

Michael
quelle
0

Wie immer, wenn Sie etwas schreiben, müssen Sie sich fragen, wer das beabsichtigte Publikum ist. Ich bin der festen Überzeugung, dass Designdokumente für aktuelle und zukünftige Peer-Entwickler zur Verfügung stehen. Das Dokument hilft ihnen zu verstehen, was ich baue oder was gebaut wurde (allgemeine Übersicht) und was noch wichtiger ist, warum. Hier können Sie die Alternativen dokumentieren, die Sie in Betracht gezogen haben, die Vor- und Nachteile der einzelnen.

Zu sagen, dass es in Ordnung ist, wenn ein Design im Kopf eines Menschen lebt, lässt Entwickler davon ab, andere Jobs zu finden und wertvolle Informationen mitzunehmen.

Ihren Code als einzige Konstruktionsdokumentation zu haben, ist wie sich mit einer Lupe in der Stadt zurechtzufinden. Eine Karte ist viel nützlicher (leider gibt es kein GPS-Äquivalent für den Quellcode).

Ich bin damit einverstanden, dass die Designdokumentation noch schneller verrottet als der Code. Und da zwischen den beiden keine Validierung möglich ist, können Sie sie nur nahe beieinander halten. IMO, ein datiertes Designdokument, liefert noch wertvolle Informationen.

MvdD
quelle