Sollte ein Designdokument eine Diskussion der Vor- und Nachteile eines bestimmten Designs enthalten oder sollte es sich auf Fakten und Gründe konzentrieren?

Ich bin gerade dabei, ein Designdokument zu aktualisieren, damit es für zukünftige Entwickler korrekt und aktuell ist.

Derzeit konzentriert sich das Dokument nur auf die Fakten und zeigt, wie das Design ist. Es gibt keine Begründung für die vorgelegten Entscheidungen. Ich glaube, es ist wichtig, die Gründe zu erfassen, damit die Entwickler wissen, warum etwas so ist, wie es ist, da dies wahrscheinlich zukünftige Entscheidungen beeinflusst. Es ist mir nicht möglich, alle Entwurfsentscheidungen zu begründen, insbesondere die, die vor Beginn der Arbeit an dem Projekt getroffen wurden, aber ich tue in dieser Abteilung, was ich kann.

Einige der Entwurfsentscheidungen sind jedoch in Anbetracht der Anforderungen des Projekts respektvoll sehr schlechte Entscheidungen. Es gibt aber auch einige gute.

Mein erster Gedanke war, dass ich eine Diskussion über Entwurfsprobleme und mögliche Lösungen oder Problemumgehungen für diese Probleme einschließen sollte, um die Aufmerksamkeit zukünftiger Betreuer zu lenken, aber ich bin nicht sicher, ob das Entwurfsdokument ein Ort für diese Art von Diskussion und Information ist. Ich möchte nicht, dass eine Design- "Kritik" dazu führt, "dieses Design neu zu reißen", während andere Leute an diesem System arbeiten und das Dokument aktualisieren, da dies eindeutig unangemessen ist.

Mein Manager würde jede Entscheidung unterstützen, also liegt es an mir. Unabhängig davon, wie ich vorgehe, wird das erstellte Dokument offiziell versioniert und Entwicklern, die am System arbeiten, zur Verfügung gestellt, in der Regel bevor sie mit der Entwicklungsarbeit beauftragt werden. Es wird erwartet, dass sich ein neuer Entwickler vor Beginn der Entwicklungsarbeiten mit den Dokumenten eines bestimmten Softwaresystems vertraut macht.

Fragen:

• Sollte sich ein Designdokument an Rohdaten ("das ist das Design") und Begründungen ("hier ist das Design") halten oder sollte es auch verwendet werden, um auf nicht fehlerhafte Probleme mit dem Design hinzuweisen, die problematisch sein könnten zukünftige Entwickler?
• Wenn das Designdokument nicht zum Erfassen dieser Informationen verwendet werden soll, welche Art von Dokument sollte erfasst werden, und was sollte mit einer Erörterung von Konstruktionsgründen, Kompromissen und bekannten Problemen (die keine Fehler sind, da Fehler nachverfolgt werden) erfasst werden mit anderen Werkzeugen)?

Wenn die Vor- und Nachteile in ein oder zwei Sätzen zusammengefasst werden können, ist es in Ordnung, sie in ein Designdokument einzufügen. Alles, was länger ist, sollte abgetrennt werden.

Wo ich derzeit arbeite, gibt es normalerweise ein separates Dokument "Designentscheidungen", in dem alle wichtigen und wichtigen Entscheidungen erfasst werden. Häufig formatiert mit einem Absatz, der das Problem beschreibt (z. B. "Einige Dateien müssen am Ende jedes Verarbeitungszyklus von einem Server zu bestimmten Benutzern verschoben werden. Dafür gibt es viele Möglichkeiten ..."), eine Tabelle mit Spalten. Lösungsbeschreibung "(wie" Dateien über FTP verschieben ")," Vorteile "(wie" Einfach zu verwaltende Benutzer ")," Nachteile "(wie" Nicht sicher genug für ABC-XYZ-Konformität ") und eine Schlussfolgerung, dass erläutert, warum eine bestimmte Entscheidung getroffen wurde (z. B. "FTP wird nicht verwendet, da bestimmte Compliance-Anforderungen nicht erfüllt werden können"). Das Designdokument verweist in der Regel nur auf die gewählte Entscheidung.

Sollte sich ein Designdokument an Rohdaten ("das ist das Design") und Begründungen ("hier ist das Design") halten oder sollte es auch verwendet werden, um auf nicht fehlerhafte Probleme mit dem Design hinzuweisen, die problematisch sein könnten zukünftige Entwickler?

Es ist nicht "entweder oder".

Niemand liest Dokumentation an erster Stelle. Sie überfliegen - bestenfalls. Schreiben Sie daher so wenig Dokumente wie möglich. Ein Dokument ist alles, wofür jemand Geduld hat. Es ist unwahrscheinlich, dass ein zweites "Nicht-Desgin" -Dokument mit "anderen Problemen" überhaupt gelesen wird.

Vorteile eines Dokuments? Die Leute könnten es lesen.

Nachteile eines Dokuments? Wenige. Meistens ist es veraltet.

Vorteile mehrerer Dokumente? Keiner.

Nachteile mehrerer Dokumente? Bitte informieren Sie sich über das DRY-Prinzip und die Programmierung. Mehrere Dokumente bedeuten mehrere Fehlerquellen. Jedes Dokument stimmt nicht mit dem anderen überein und stimmt nicht mit dem Code überein. Das ist ziemlich offensichtlich. Dies ist der Weg des Wahnsinns.

Vermeiden Sie das Auswringen von Hand.

Ein Pro-und-Contra-Dokument kann in unbestimmte Tiefen von Was-wäre-wenn- und attraktiven Ärgerdiskussionen vordringen.

Wenn Sie der Meinung sind, dass es notwendig ist, Vor- und Nachteile zu präsentieren, halten Sie es kurz und auf den Punkt.

Konzentriere dich auf das, was ist.

Behalten Sie, was nicht bis auf die Knochen reicht.

Wenn Sie Benchmarks, Studien oder tatsächlich untersuchte Alternativen durchgeführt haben, dokumentieren Sie dies. Wenn Sie jedoch nur Alternativen in Betracht ziehen, minimieren Sie diese.

Dies sollte nicht Ihre persönliche Geschichte der Prüfung und Trübsal sein.

• Hatte ein Problem? Repariert? Hat Wochen gedauert? Wirklich gekämpft? Kaum eine interessante Anekdote. Es ist im Code festgelegt. Die vorherigen Versionen, falschen Versionen, fehlerhaften Versionen und leistungsschwachen Versionen spielen keine Rolle. Sie sind bestenfalls Blog-Futter.

• Haben Sie noch ein Problem? Nicht behoben? Das heißt, es gibt Alternativen. Dokumentieren Sie dies.

Es gibt 3 wichtige Fakten im Entscheidungsprozess:

• Was wurde versucht und hat nicht funktioniert (und warum hat es nicht funktioniert, weil Sie ein sich bewegendes Ziel anvisieren)
• Was ist
• Was könnte sein (nur darauf warten, dass X implementiert wird ...)

Abgesehen von "Was ist" verwirren jedoch alle anderen den Leser und hindern ihn daran, das System zu stören.

Ich mag die Idee, die anderen 2 zu erfassen, obwohl sie für das Erlernen des Systems weniger interessant sind, können sie beim Ändern Zeit sparen.

Daher würde ich auf der Idee aufbauen, die @FrustratedWithFormsDesigner enthüllt, mit einer Wendung. Anstatt noch ein weiteres Dokument mit einem eigenen Lebenszyklus zu erstellen, würde ich einen Abschnitt im Anhang behandeln. Dann würde ich für jede Entscheidung, die erörtert werden sollte, auf den entsprechenden Eintrag im Anhang verweisen.

Ja. In einem Designdokument sollten die Vorteile, Risiken und Annahmen des beschriebenen Designs erläutert werden. Ein Designdokument hat mehrere Zwecke:

1. Schreiben Sie das Design so auf, dass jeder es versteht und dass das Verständnis eines jeden nicht mit der Zeit schwankt.

2. Kommunizieren Sie das Design nicht-technischen Personen, die an dem Projekt arbeiten.

3. Unterstützung bei der Planung, Ressourcenzuweisung, Kostenschätzung und anderen Arten der Planung.

4. Wird ein wichtiger Bestandteil der gesamten Projektdokumentation. Wenn Sie einem laufenden Projekt beitreten oder ein abgeschlossenes Projekt warten müssen, ist das Leben viel einfacher, wenn es ein gut geschriebenes Designdokument gibt.

5. Ist oft eine der vertraglich geforderten Leistungen.

(Es gibt wahrscheinlich noch andere, aber das ist ein guter Anfang.)

Jeder dieser Zwecke wird durch ein Designdokument unterstützt, das klar erklärt, warum dieses Design ausgewählt wurde und welche Risiken damit verbunden sind:

1. Es ist wichtig, dass alle im Team die Risiken und Vorteile kennen, damit sie zusammenarbeiten können, um diese Risiken zu vermeiden und die Vorteile des Designs optimal zu nutzen.

2. Für nicht-technische Teammitglieder ist es oft wichtiger, die Risiken und Vorteile zu kennen als die Einzelheiten des Entwurfs.

3. Risikomanagement ist eines der wichtigsten Dinge, die ein Projektmanager tun kann, um den Erfolg sicherzustellen. Der erste Schritt besteht darin, die Risiken zu identifizieren, die verwaltet werden müssen. Es sollte Aufgabe eines Managers sein, zu entscheiden, wie mit Risiken umgegangen werden soll. Es liegt jedoch in der Verantwortung des Designers, auf bekannte Risiken des Entwurfs hinzuweisen.

4. Auch wenn ein Risiko kein Problem mehr darstellt, ist es oft nützlich, es dokumentiert zu haben, da es dabei helfen kann, die Situation zum Zeitpunkt der Erstellung des Entwurfs zu erklären. Das kann einen Betreuer zu der Entscheidung bringen: "Okay, sie haben es damals so gemacht, weil ... aber das ist kein Problem mehr, also kann ich diesen Code durch eine einfachere, schnellere Implementierung ersetzen." Gleiches gilt natürlich für die Leistungen.

5. Wenn Sie für einen Kunden an einem Projekt arbeiten, ist es besonders wichtig, Risiken und Vorteile zu dokumentieren. Dies macht den Kunden darauf aufmerksam, dass unter bestimmten Umständen etwas schief gehen kann oder dass das Anfordern von Änderungen am Design einige der versprochenen Vorteile gefährden kann.

Ich gehe von der Frage aus, ob Sie mit einem vorhandenen Designdokument für ein System arbeiten, das bereits implementiert wurde. In diesem Fall handelt es sich bei vielen der möglichen Risiken nicht mehr um Risiken. Daher ist es wenig sinnvoll, sie nachträglich zu dokumentieren. Im Nachhinein haben Sie jedoch den Vorteil, dass Sie die Teile des ursprünglichen Designs sehen können, die nicht so gut geklappt haben. Ich denke, Sie sollten entweder: einen separaten Abschnitt hinzufügen, der aktuelle Problembereiche identifiziert und Lösungen vorschlägt (einschließlich der damit verbundenen Risiken!); oder erstellen Sie ein separates Dokument, das dasselbe tut. Dieser neue Abschnitt / dieses neue Dokument wird möglicherweise zum Designdokument für die nächste Version der Software.

Hier ist ein Blogeintrag zum Schreiben von Designdokumenten , die Sie möglicherweise hilfreich finden.

Wenn es triftige Gründe gab, offensichtliche oder Standardlösungen zu vermeiden, sollten diese zur Kenntnis genommen werden. Sie werden jemandem viel Ärger ersparen. Eine bestimmte Technologie kann sich jedoch im Laufe der Zeit verbessern, sodass Ihre Gründe möglicherweise nicht zutreffen. Ein zukünftiger Entwickler kann dann sein eigenes Urteilsvermögen einbringen.

Ich weiß nicht, ob es von großem Nutzen ist, auf all die Mängel hinzuweisen. Es ist möglicherweise nicht praktikabel, Änderungen vorzunehmen, da sonst andere Prioritäten gesetzt werden. Möglicherweise werden Sie einige davon in naher Zukunft beheben, und dies ist nur eine weitere Sache, die aktualisiert werden muss.

Ich persönlich würde es nicht in das Designdokument aufnehmen. Ein Designdokument sollte beschreiben, wie es ist, nicht warum es ist.

Wenn Sie der Meinung sind, dass eine Hintergrundgeschichte erforderlich ist, warum das Design so ist, wie es ist, sollten Sie diese vielleicht in einen Wiki-Artikel (oder in eine Wissensdatenbank, die Ihr Unternehmen verwendet) einfügen, damit es eine Geschichte des gibt Entwicklung des Designs. Die Leute können es lesen, bearbeiten und Vorschläge hinzufügen. Auf diese Weise handelt es sich eher um eine offene Diskussion als um ein kurzes Schlagen in einem Dokument.

Ich stimme Ihnen zu, wenn es darum geht, Gründe in das Designdokument aufzunehmen.

Wie auch immer,

Während ich ein von jemand anderem geschriebenes Designdokument aktualisiere, würde ich bescheiden bleiben und nicht versuchen zu erraten, warum eine solche Entscheidung getroffen wurde.

So,

Ich möchte nur Gründe für Änderungen an der Konstruktion während der Wartung anführen.