Warum das Schreiben von Software-Designdokumenten wichtig ist

Herzlichen Glückwunsch, Sie sind ein kompetenter unabhängiger Entwickler. Von Ihren bescheidenen Anfängen, vielleicht als Tester, haben Sie sich zu einem Teamentwickler entwickelt, dann zu einem leitenden Entwickler, und jetzt haben Sie einen weiteren Sprung, den größten von allen, gemacht, um direkt mit Kunden zu arbeiten.

Aber wo die anderen Übergänge linear waren, war dieser letzte exponentiell. Während Sie in der Vergangenheit Ihre Marschbefehle von einem Arbeitgeber erhielten, der mit Kunden zusammenarbeitete oder selbst im Softwaregeschäft tätig war, liegen jetzt alle Verantwortlichkeiten, die früher zwischen Expertentests, Programmmanagement usw. verteilt waren, ganz bei Ihnen. Und jetzt arbeiten Sie mit Kunden, die nicht in der Softwarebranche tätig sind; Sie sind in einem anderen Unternehmen tätig, das eine Software benötigt, und sie haben keine klare und genaue Vorstellung davon, was sie von Ihnen erwarten. Das ist eine viel größere Herausforderung, als es den Anschein hat.

*Hinweis:* Hier beschreibe ich kleinere Kunden, die von ihrem Entwickler eine Ein-Mann-Armee wollen. Es ist nicht der einzige Weg, den ein Freiberufler einschlagen kann, und das sind nicht die einzigen Kunden, mit denen wir bei Toptal zusammenarbeiten, aber es ist der Weg, den ich am meisten mag. Wenn Sie in einem Team und nicht alleine arbeiten, treffen einige der folgenden Punkte natürlich nicht zu. Wenn Sie beispielsweise agile Methoden oder Scrum verwenden, möchten Sie Ihre Meilensteine ​​wahrscheinlich etwas anders strukturieren.

Sie haben alle von der überragenden Bedeutung der Kommunikation gehört. Sie können nicht arbeiten, indem Sie über Skype ein paar Sätze mit knapper Beschreibung erhalten und sagen: „Bis in drei Monaten, wenn ich fertig bin.“ Sie müssen mit Ihrem Kunden in Kontakt bleiben und in jeder Phase Ihrer Arbeit sicherstellen, dass Sie übereinstimmende Vorstellungen von der Zielsetzung haben, denn es kommt tatsächlich selten vor, dass Ihnen ein Kunde Wireframes und ein detailliertes Pflichtenheft zusendet. Sie erhalten eine sehr allgemeine Vorstellung davon, was die Software tun, aussehen und fließen soll. Wenn Sie eine Bewerbung basierend auf der oberflächlichen Beschreibung schreiben, mit der Sie normalerweise beginnen, besteht fast keine Chance, dass Ihr Kunde mit dem Ergebnis zufrieden ist. In jeder Phase müssen Sie sich der Einigung nähern.

Nachdem sie jahrelang in Unternehmen gearbeitet haben, die selbst in der Softwarebranche tätig waren, wo alle im Team aus derselben Kultur stammten, dieselbe Muttersprache sprachen, auf demselben Flur arbeiteten, sich täglich trafen usw., war es bemerkenswert, dass die Das Unternehmen hat die Hälfte der Zeit immer noch nicht bekommen, was es wollte. Täuschen Sie sich nicht: Die Herausforderung hier ist enorm.

Warum Softwaredesign-Dokumente wichtig sind

Wenn Sie also ein neues Projekt übernehmen, müssen Sie klare und vereinbarte Designziele haben, bevor Sie Xcode oder Visual Studio überhaupt öffnen . Und diese Ziele sollten in einem Spezifikationsdokument festgelegt werden. Wenn der Kunde keines geschrieben hat, sollten Sie es schreiben und ihm zur Überprüfung vorlegen, bevor Sie Ihre IDE überhaupt öffnen. Und wenn Sie auf einen Kunden stoßen, der sagt: „Wir haben keine Zeit für Konstruktionsdokumente“, sollten Sie das Projekt offen lassen, weil Sie Probleme haben. Die Spezifikation muss nicht besonders lang sein; Es kann nur ein paar Seiten umfassen, sollte aber zumindest die Benutzeroberfläche gestalten, Wireframes enthalten (falls es eine UI-Komponente gibt) und Fertigstellungsmeilensteine ​​festlegen.

Ohne dieses Dokument landen Sie in einer Schleife erbitterter Zweideutigkeiten, Kunden bestreiten, was sie Ihnen oder was Sie ihnen gesagt haben, senden wütend Cut-and-Pastes früherer Kommunikationen, interpretieren und argumentieren, bis der Zeitpunkt kommt, an dem der Kunde es verlangt dass Sie Änderungen vornehmen, um die Anwendung in Übereinstimmung mit dem zu bringen, „was sie tatsächlich verlangt haben“, und erwartet, dass Sie diese Änderungen ohne Bezahlung vornehmen.

Mit diesem Softwaredesign-Dokument haben Sie eine Antwort auf solche Spitzfindigkeiten: Wenn es zu Meinungsverschiedenheiten kommt, können Sie sich auf die Spezifikation beziehen, der der Kunde zugestimmt und die er unterschrieben hat, und darauf hinweisen, dass Sie sie buchstabengetreu erfüllt haben. Anstatt wütend zu argumentieren, nehmen Sie Änderungen und Klarstellungen am Dokument vor. Wenn überhaupt, wird sich der Kunde dafür entschuldigen, dass er die Ungenauigkeit überhaupt durchgehen ließ.

Wir alle wollen zufriedene Kunden. Wir alle wünschen uns ein freundschaftliches Arbeitsverhältnis. Und wir alle wollen stolz auf eine gut gemachte Arbeit sein. Aber diese können nicht erreicht werden, wenn überhaupt unklar ist, was der Job eigentlich ist . Wenn Ihr Kunde sagt, dass ein Designdokument zu viel zusätzliche Arbeit ist, ist es Ihre Aufgabe, ihm zu erklären, dass die wirkliche zusätzliche Arbeit entsteht, wenn aufgrund eines Missverständnisses Änderungen vorgenommen werden müssen. Wenn der Kunde immer noch darauf besteht, dass Sie ohne ein solches Dokument vorrücken, sollten Sie die Tatsache akzeptieren, dass Sie eine nicht tragfähige Beziehung haben, und weggehen.

Was sollte die Software-Design-Spezifikation eigentlich vorgeben?

Es sollte mindestens eine Beschreibung der gewünschten Anwendung, Kriterien für die Fertigstellung und Meilensteine ​​enthalten. Denken Sie daran, dass Sie etwas teilen, das am besten als Anforderungs- und Funktionsdokument beschrieben wird, nicht als Implementierungsspezifikation. Und wenn eine bestimmte Implementierung kein erklärtes Kundenziel ist, liegt es an Ihnen, wie Sie es zum Laufen bringen.

Benutzeroberfläche

Die meisten Projekte sind Anwendungen, keine Bibliotheken oder Frameworks. Aber wenn Sie eines davon als Ergebnis haben, können Sie sich glücklich schätzen, denn die Benutzeroberfläche ist bei weitem die problematischste Komponente Ihrer Designdokumentvorlage und führt fast immer zu Missverständnissen. Viele Kunden schicken Ihnen perfekte Illustrationen, die in einem Grafikeditor von einem Grafikdesigner erstellt wurden, der kein Programmierer ist. Aber das Problem ist: Diese Abbildungen sagen nichts über Animationen, Steuerungszustände (z. B. Ist diese Schaltfläche deaktiviert? Verschwindet sie, wenn sie nicht verwendet werden kann?) oder sogar darüber, welche Aktionen auszuführen sind, wenn eine Schaltfläche gedrückt wird.

Bevor Sie beginnen, den Code hinter diesen Illustrationen zu schreiben, sollten Sie in der Lage sein, all diese Fragen zu beantworten. Konkret sollten Sie wissen:

1. Sind Steuerelemente immer sichtbar und/oder aktiviert? Unter welchen Bedingungen ändern sich ihre Zustände?
2. Sieht aus wie eine Bitmap – ist es eine Schaltfläche?
3. Welche Übergänge treten zwischen diesen Zuständen und Ansichten auf? Und wie sollen sie animiert werden?

Wenn es an Ihnen liegt, die Benutzeroberfläche für die Zustimmung des Clients zu generieren, machen Sie dasselbe umgekehrt: Verwenden Sie ein Wireframe-Tool und erstellen Sie einen vollständigen Satz von Bildschirmlayouts, einschließlich aller Varianten, die die Ansichten in verschiedenen Anwendungszuständen zeigen. Dies kann eine erschöpfende und langwierige Arbeit sein, aber Sie werden es nicht bereuen – es kann Sie davor bewahren, riesige Mengen an Code neu zu schreiben und Schnittstellen aufgrund eines kleinen Missverständnisses mit großen Auswirkungen neu zu erstellen. Wenn Sie eine duale Anwendung erstellen (z. B. sowohl für iPhone als auch für iPad), erstellen Sie separate Wireframes für beide.

Bildschirmabmessungen sind ebenfalls wichtig. Es gibt (zum Zeitpunkt des Schreibens) drei Größen von iPhone-Bildschirmen. Separate Wireframes für 3,5-Zoll- und 4-Zoll-Bildschirme sind wahrscheinlich übertrieben, aber Sie müssen sie möglicherweise erstellen. In den meisten Fällen können Sie einfach die Proportionen ändern.

Wenn Ihr Kunde Ihnen Grafiken liefert, stellen Sie sicher, dass sie die richtige Größe und das richtige Seitenverhältnis haben; Das Morphen von Bitmaps mit Text oder Objekten (z. B. Kreisen) führt zu Verzerrungen. Wenn sie nicht übereinstimmen, bitten Sie den Kunden, sie mit übereinstimmenden Größen neu zu erstellen. Gehen Sie nicht davon aus, dass Sie einen 3,5-Zoll-Begrüßungsbildschirm in einen 4-Zoll-Begrüßungsbildschirm dehnen und einfach damit rollen können.

Funktionalität

Wichtige Fragen, die im Dokument zum Anwendungsdesign gestellt werden sollten:

• Was macht die Anwendung und wie schnell macht sie das?
• Was sind mögliche Fehlerbedingungen und wie werden sie gehandhabt?
• Welche einmaligen Vorgänge werden bei der ersten Ausführung (dh nach der Installation) durchgeführt?
• Wenn der Benutzer Einträge jeglicher Art (z. B. Lesezeichen) erstellt, welche Einschränkungen gibt es?

Verallgemeinern Sie diese Ideen und seien Sie so detailliert und gründlich wie möglich – denn Fehler oder Missverständnisse bedeuten hier das Umschreiben von Code.

Meilensteine

Ihre Spezifikationsvorlage sollte klare Meilensteine ​​enthalten. Wenn Ihr Kunde das Funktions- und Benutzeroberflächendesign schreibt, sollten Sie sich anschließend auf eine Reihe von Meilensteinen einigen. Manchmal sind dies auch Abrechnungsschwellenwerte, aber zumindest bieten sie eine klare Metrik für den Abschluss. Meilensteine ​​können sich auf Funktionalität und/oder Komponenten beziehen; es kann sich sogar um separate Anwendungen handeln, wenn der Gig eine Reihe von Liefergegenständen umfasst. Wenn möglich, sollten Meilensteine ​​ungefähr gleich lang sein.

Beispiel für eine Software-Design-Spezifikation

Hier werde ich die Beispielstruktur eines richtigen Designdokuments entwerfen. Natürlich sollte diese Vorlage nach Bedarf angepasst werden. Ein weiteres Beispiel finden Sie in der Musterspezifikation von Joel Spolsky, die auf dieser Beschreibung basiert. Er geht etwas anders an das Dokument heran, teilt aber eine ähnliche Meinung.

Erklärung der Ziele

Fügen Sie einen kurzen Absatz hinzu, der das Projekt und seine Zielgruppe beschreibt.

Funktionsbeschreibung

Was macht die Anwendung ? Welche Anwendungszustände (High-Level-Beschreibungen von Kernbenutzerszenarien) werden dem Benutzer begegnen?

Ihre Funktionsbeschreibung könnte beispielsweise so aussehen:

• Erster Lauf
• Erstellen eines neuen _____ (Spiel, Suche usw.)
• Operationen
• Hintergrund- und Vordergrundverhalten

Benutzeroberfläche

Fügen Sie Wireframes für jede Seite mit detaillierten Beschreibungen von Folgendem hinzu:

• Jedes Steuerelement, einschließlich Status (aktiviert/deaktiviert/hervorgehoben) und Operationen.
• Unterstützte Orientierungen und Übergänge zwischen ihnen.
• Funktionalität dargestellt.
• Fehlerbehandlung.
• Abmessungen und Einschränkungen.

Hier sind die Wireframes, die sich auf meine neueste iOS-App NotifEye beziehen:

Wenn Sie interessiert sind, habe ich diese Mockups mit dem Wireframing-Tool von Balsamiq erstellt.

Ihre UI-Beschreibung könnte beispielsweise so aussehen:

• Navigationsleiste
  • Linke Navigationssteuerung: Zurück zur Startseite
  • Titelleiste: Name des aktuellen Bildschirms oder Vorgangs
  • Schaltfläche „Neu“: Erstellen Sie ein neues Ding
• Tabellenansicht
  • Abschnitt 0: Titel des Abschnitts
  • Abschnitt 0 Zeilen:
    • Zeilensteuerung 0 (z. B. Bild)
    • Textzeile 0
    • Textzeile 2

Meilensteine

Wie oben beschrieben, Fristen für die Fertigstellung und erwartete Leistungen.

Der Abschnitt „Meilensteine“ in Ihrer Designdokumentvorlage könnte beispielsweise so aussehen:

1. Fassadenanwendung mit Bildschirm und temporären Übergängen und Beispielbildern/-text
2. Kommunikationsprotokoll: Anwendung verbindet sich mit Netzwerk/Server
3. Funktionaler Meilenstein 1: …
4. Alpha-Anwendung (mit vollem Funktionsumfang)
5. Stabilität
6. Freisetzung

Stellen Sie sicher, dass die Softwaredokumentation relevant bleibt

Ich will damit nicht sagen, dass die Designphase vorbei ist, wenn Sie und Ihr Kunde sich auf ein Spezifikationsdokument geeinigt haben. Es wird immer Details geben, die keiner von Ihnen berücksichtigt hat, und sowohl Sie als auch der Kunde werden beim Betrachten der Zwischenergebnisse auf neue Ideen, Designänderungen, unerwartete Designfehler und nicht umsetzbare Vorschläge stoßen.

Das Design wird sich weiterentwickeln, und die Änderungen sollten in Ihrem Dokument erfasst werden. In meiner 25-jährigen Erfahrung habe ich noch nie an einem Projekt gearbeitet, bei dem dies nicht passiert ist – und dazu gehören auch meine eigenen Anwendungen (dh wo ich mein eigener Kunde war). Schon damals habe ich ein Designdokument mit detaillierten Spezifikationen erstellt und bei Bedarf angepasst.

Bleiben Sie vor allem in Kontakt. Wenden Sie sich mindestens mehrmals pro Woche an Ihren Kunden, berichten Sie über Ihre Fortschritte, bitten Sie um Klärung und stellen Sie sicher, dass Sie identische Visionen teilen. Versuchen Sie als Lackmustest für Ihre Kommunikation sicherzustellen, dass Sie und Ihr Kunde die gleichen Antworten auf diese drei Fragen geben:

1. Woran hat der Entwickler gerade gearbeitet?
2. Woran arbeitet der Entwickler gerade?
3. Woran wird der Entwickler als nächstes arbeiten?