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

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.

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.

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!

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.

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).

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.