Wie schreibe ich schnell und effizient eine Funktionsbeschreibung?

Also habe ich gerade einige großartige Artikel von Joel über Spezifikationen hier gelesen . (Wurde 2000 geschrieben !!) Ich habe alle 4 Teile gelesen, suche aber nach methodischen Ansätzen, um meine Spezifikationen zu schreiben.

Ich bin der einzige einsame Entwickler, der an dieser ziemlich komplizierten App (oder App-Familie) für ein sehr bekanntes Finanzunternehmen arbeitet.

Ich habe noch nie etwas so Ernstes gemacht, ich habe angefangen, so etwas wie eine schlechte Spezifikation, einen Überblick über einige Arten zu schreiben, und es hat eine Menge meiner Zeit verschwendet.

Ich habe auch 3 Mockup-Dinger für meinen Kunden gemacht, damit ich ein gutes Verständnis dafür habe, was sie wollen. Außerdem wurde eine Vorschau veröffentlicht (eine wegwerfbare App mit dem grundlegendsten Workflow), und ich habe nur einige der Kern- / Basissysteme geschrieben und getestet.

Ich denke, der Fehler, den ich bisher gemacht habe, besteht nicht darin, eine detaillierte Spezifikation zu schreiben, also komme ich jetzt dazu.

Das Ganze besteht also aus

• Eine MVC-Website (für Administratoren und zum Anzeigen von Daten)
• 2 Silverlight-Module (für 2 spezifische Aufgaben)
• 1 Desktop-Anwendung

Ich habe wenig Zeit, Ressourcen und muss dafür sorgen, dass diese Leute es genauso schnell und schmerzlos nachlesen.

• Also, wie gehe ich vor, ich suche nach Tipps, nach etwas aus der realen Welt, wie macht ihr das normalerweise?
• Machen Sie aus jedem Dialog / Formular / jeder Seite einen Schein-Screenie?

Ich überlege, ein Dummy-ASP.NET Web Forms-Projekt zu erstellen , dann HTML- Dateien in Ordner einzufügen und es so zu gestalten, dass es meiner MVC-URL-Struktur entspricht.

Haben Sie dann einen Abschnitt in der Spezifikation für die Website und schreiben Sie eine Seite für jede URL, die ich mit einem Screenie habe.

Für meine Win Forms-App habe ich etwas von einem Demo-Win Form-Projekt gemacht. Würde ich dann alles wie in der echten App in einen Dialog stellen oder strukturieren und dann einen Screenshot davon machen?

Für einige Hintergrundinformationen zu dieser Frage. Ich war schon immer ein verrückter Typ, der direkt zum Code gesprungen ist. Das hat funktioniert, aber für die App, an der ich arbeite, ist es nicht nur komplex, sondern für ein sehr angesehenes und großes Unternehmen, und ich muss es mir holen richtig!

(Und es ist soweit gut gelaufen, heute habe ich eine Demo der Preview-Version gegeben, die vielen Leuten gefallen hat !! = D)

Wenn ich das anfängliche Design richtig einsetze, habe ich auch ein großartiges Geschäft mit diesem Unternehmen. Es gibt bereits viele, die über neue "großartige" Funktionen nachdenken, für die sie bereit sind, zu zahlen.

Haben Sie Teil 2 des Artikels oder seine Beispielspezifikation gelesen ? Sie verkörpern ein paar wichtige Prinzipien beim Schreiben einer Spezifikation.

• Überdesign nicht. Der Zweck des Schreibens der Spezifikation besteht darin, Sie zu veranlassen, über wichtige Dinge nachzudenken, z. B. was passiert, wenn ein Fehler auftritt, und wie Sie erwarten, dass der Benutzer mit dem System interagiert. Sie müssen nicht übermäßig detailliert vorgehen, um etwas zu erhalten, mit dem Sie arbeiten können. Sie brauchen jedoch Details.
• Es geht um Kommunikation. Der Zweck der Spezifikation besteht darin, eine gemeinsame Einigung darüber zu erzielen, was getan werden muss. Es ist kein eisernes Dokument, das die Kraft des Gesetzes erfordert. Es ist ein Tool, mit dem Sie Ihren Kunden besser verstehen können, und Ihr Kunde kann besser verstehen, was Sie für ihn tun möchten.

Der beste Rat ist, so viel zu schreiben , dass Sie genau wissen, was Sie tun müssen. Wenn Sie offene Fragen haben, dokumentieren Sie diese in der Spezifikation und erhalten Sie Antworten von Ihrem Kunden. Sobald Sie ausreichend verstanden haben, was benötigt wird , hören Sie auf .

Wenn Sie nicht aufpassen, wird das Dokument ein Eigenleben annehmen. Es sollte einen Zweck haben, fügen Sie dem Dokument nichts hinzu, was nicht zu diesem Zweck passt. Es sollte leicht zu warten sein. Wenn Sie Ihre gesamten detaillierten Klassendiagramme zusammen mit anderen Details haben, die wirklich zu einem Komponententest gehören, werden Sie entweder das Dokument aufgeben, weil der Unterhalt zu groß ist, oder Sie werden das Projekt nie zum Abschluss bringen.

Über das Schreiben

Für Menschen zu schreiben ist schwer . Tatsächlich ist es am schwierigsten, zu wissen, wie man anfängt und wann man aufhört . Am Anfang muss man einfach etwas tun. Mein Rat für den Umgang mit diesen beiden schwierigsten Aspekten lautet:

• Kenne deine Zuhörer. Wer soll die Spezifikation lesen? Wenn es nur Sie und der Kunde sind, dann schreiben Sie an diesen. Wenn Sie jemanden haben, der für das Testen verantwortlich ist, haben Sie auch einige Notizen für ihn.
• Beginnen Sie mit der Sache mit der höchsten Priorität. Während die Authentifizierung wichtig ist, ist der Anmeldebildschirm wahrscheinlich das am besten verstandene Stück, das die meisten Leute schreiben müssen. Konzentrieren Sie sich stattdessen auf die Funktion, die Ihre Benutzer am meisten benötigen. Wissen Sie, dieser Teil, der ihnen Geld einbringt, ist der ganze Grund, warum sie die Software brauchen.
• Füllen Sie die Details aus, sobald die Fragen auftauchen und Sie Antworten erhalten. Halten Sie die Dinge bei Bedarf mit Serviettenzeichnungen wirklich einfach, bis der Kunde mit dem Arrangement zufrieden ist. Es ist wichtig zu wissen, um welche Informationen es sich handelt und wie sie verwendet werden.
• Stoppen Sie, wenn das Hinzufügen von mehr keinen Wert hinzufügt. Es gibt einige Details, die Sie in einer Spezifikation einfach nicht wollen. Sie müssen wissen, wann Sie das Richtige haben. Sie müssen nicht wissen, dass eine Methode mit dem Namen "albaquerque" eine Variable enthält. Das ist Quellcode, keine Spezifikation.