Jak napisać specyfikację funkcjonalną szybko i skutecznie

17

Właśnie przeczytałem kilka fantastycznych artykułów Joela na temat specyfikacji tutaj . (Został napisany w 2000 roku!) Przeczytałem wszystkie 4 części, ale szukam metodycznego podejścia do pisania moich specyfikacji.

Jestem jedynym samotnym twórcą, pracującym nad dość skomplikowaną aplikacją (lub rodziną aplikacji) dla bardzo znanej firmy finansowej.

Nigdy nie robiłem czegoś tak poważnego, zacząłem pisać coś w rodzaju złej specyfikacji, pewnego rodzaju przegląd i to zmarnowało MNIE dużo czasu.

Zrobiłem też 3 makiety dla mojego klienta, więc dobrze rozumiem, czego chcą. Wydałem również wersję zapoznawczą (wyrzuconą działającą aplikację z najbardziej podstawowym przepływem pracy), a ja napisałem i przetestowałem tylko niektóre systemy podstawowe / podstawowe.

Myślę, że błąd, który popełniłem do tej pory, nie polega na napisaniu szczegółowej specyfikacji, więc przechodzę do tego teraz.

Więc całość składa się z

  • Witryna MVC (dla administratorów i przeglądania danych)
  • 2 moduły Silverlight (dla 2 określonych zadań)
  • 1 aplikacja komputerowa

Nie mam czasu, zasobów i muszę to szybko zrobić, muszę też upewnić się, że ci faceci przeczytają to równie szybko i bezboleśnie.

  • Więc jak mam to zrobić, szukam jakichkolwiek wskazówek, rzeczy z prawdziwego świata, jak to robicie?
  • Czy robisz próbną analizę każdego okna dialogowego / formularza / strony?

Zastanawiam się nad stworzeniem fikcyjnego projektu ASP.NET Web Forms, a następnie wypełnieniem plików HTML w folderach i nadaniem mu wyglądu mojej struktury URL MVC.

Następnie posiadam sekcję specyfikacji witryny i zapisuję stronę dla każdego adresu URL, który otrzymałem za pomocą screenie.

W przypadku mojej aplikacji Win Form stworzyłem coś w rodzaju projektu demonstracyjnego Win Form. Czy powinienem wtedy otworzyć okno dialogowe lub uporządkować wszystko tak, jak w prawdziwej aplikacji, a następnie zrzut ekranu?


Dla niektórych podstaw do tego pytania. Zawsze byłem szalonym facetem, który skakał do kodu, który działał OK, ale dla aplikacji, nad którą pracuję, jest to nie tylko skomplikowane, ale dla bardzo renomowanej i dużej firmy i muszę to zdobyć dobrze!

(I jak dotąd szło dobrze, dziś dałem demo wersji zapoznawczej, która spodobała się wielu osobom !! = D)

Jeśli uda mi się poprawnie opracować początkowy projekt, będę miał świetny interes z tą firmą, wielu już myśli o nowych „niesamowitych” funkcjach, za które są gotowi zapłacić.

gideon
źródło
Czy to dla ciebie? Czy klient tego zażądał? Czy spodziewasz się, że do zespołu dołączy więcej programistów?
JeffO
Ma to głównie pomóc w rozwoju. Od czasu do czasu dostaję przypadkowych facetów od finansów, którzy mówią mi „och, powinniśmy zrobić xxx lub yyy”, kiedy już o tym rozmawiamy, a czasami na niektórych spotkaniach ludzie po prostu sugerują losowe funkcje, najgorsze jest to, że nigdy nie mam odpowiedniego sposobu dodanie dodatkowych funkcji za dodatkową opłatą, ponieważ moja tak zwana specyfikacja wcześniej była tylko podsumowaniem! Zasadniczo mam najwięcej problemów, o których wspomina Joel Spolsky w swoim artykule, gdy nie piszesz specyfikacji.
gideon

Odpowiedzi:

22

Czy czytałeś część 2 artykułu lub jego przykładową specyfikację ? Zapisują one kilka ważnych zasad podczas pisania specyfikacji.

  • Nie przeprojektowuj. Celem napisania specyfikacji jest zmuszenie Cię do myślenia o ważnych rzeczach, takich jak to, co dzieje się, gdy wystąpi błąd, i to, jak oczekujesz interakcji użytkownika z systemem. Nie musisz wprowadzać nadmiernych szczegółów, aby uzyskać coś, z czego możesz pracować. Potrzebujesz jednak szczegółów.
  • Chodzi o komunikację. Celem specyfikacji jest osiągnięcie wspólnego porozumienia co do tego, co należy zrobić. To nie jest ironiczny dokument, który wymaga mocy prawa. Jest to narzędzie, które pomoże Ci lepiej zrozumieć swojego klienta i klienta, aby lepiej zrozumieć, co chcesz dla nich zrobić.

Najlepszą radą jest napisać wystarczająco dużo , abyś wiedział, co musisz zrobić. Jeśli masz otwarte pytania, udokumentuj je w specyfikacji i uzyskaj odpowiedzi od swojego klienta. Gdy odpowiednio zrozumiesz, co jest potrzebne, przestań .

Jeśli nie będziesz ostrożny, dokument zacznie żyć własnym życiem. Powinien mieć jeden cel, nie dodawaj do dokumentu niczego, co nie pasuje do tego celu. Powinno być łatwe w utrzymaniu. Jeśli masz tam wszystkie szczegółowe diagramy klas wraz z innymi szczegółami, które naprawdę należą do testu jednostkowego, albo porzucisz dokument, ponieważ utrzymanie jest zbyt duże, albo nigdy nie ukończysz projektu.


O pisaniu

Pisanie dla ludzi jest trudne . W rzeczywistości dwie najtrudniejsze rzeczy związane z pisaniem to umiejętność rozpoczęcia i wiedza, kiedy przestać . Na początku musisz coś zrobić. Moja rada dotycząca radzenia sobie z tymi dwoma najtrudniejszymi aspektami to:

  • Poznaj swoich odbiorców. Kto powinien przeczytać specyfikację? Jeśli to tylko ty i klient, to do tego piszesz. Jeśli masz osobę odpowiedzialną za testowanie, również masz dla niej notatki.
  • Zacznij od rzeczy o najwyższym priorytecie. Chociaż uwierzytelnianie jest ważne, ekran logowania jest prawdopodobnie najlepiej zrozumiałym utworem, który większość ludzi musi napisać. Zamiast tego skup się na tej funkcji, której najbardziej potrzebują Twoi użytkownicy. Wiesz, ta część, która zarabia na nich pieniądze i jest jedynym powodem, dla którego potrzebują oprogramowania.
  • Podaj szczegóły, gdy pojawią się pytania i otrzymasz odpowiedzi. Zachowaj prostotę dzięki rysunkom serwetek, jeśli to konieczne, dopóki klient nie będzie zadowolony z układu. Ważne jest, aby wiedzieć, jakie informacje są zaangażowane i jak będą z nich korzystać.
  • Zatrzymaj, gdy dodanie więcej nie doda wartości. Jest kilka szczegółów, których po prostu nie chcesz w specyfikacji. Musisz wiedzieć, kiedy masz właściwą rzecz. Nie musisz wiedzieć, że w metodzie o nazwie „albaquerque” znajduje się zmienna. To kod źródłowy, a nie specyfikacja.
Berin Loritsch
źródło
+1 dzięki za odpowiedź. tak. Przeczytałem wszystkie 4 części artykułu Joelsa. A co z całym procesem screenie, czy najpierw stworzyłbym atrapowe (gładko wyglądające) strony i formularze? Żebym wiedział, co muszę napisać? Czy mogę zacząć pisać?
gideon
Zacznij od tego, co wiesz. Uprość to, abyś nie ugrzęzł, czyniąc go ładnym. Potrzebujesz pomocy kogoś innego, jeśli pójdziesz tą drogą (zabiera to trochę czasu, którego nie masz). Podczas gdy ładne specyfikacje są łatwiejsze do strawienia, masz przed sobą dużo pracy.
Berin Loritsch,