Wstęp

Drogi czytelniku, jeśli trafiłeś na ten artykuł, to całkiem możliwe, że szukasz informacji o tym, jak tworzyć specyfikacje wymagań dla oprogramowania. Niezależnie od tego, czy jesteś osobą z doświadczeniem w tworzeniu takich dokumentów, czy też zupełnie “zielony”, ta publikacja wraz ze wzorem ma na celu przedstawienie mojej koncepcji tworzenia takiej specyfikacji. Absolutnie nie jest to jedyny słuszny sposób na tworzenie tego typu opisów. Nie twierdzę też, że jest najlepszy i optymalny. Nie jest nawet w 100% oryginalny, bo czerpie przecież pełnymi garściami z różnych doświadczeń inżynierii oprogramowania.

Niemniej jest to spójne podejście, przetestowane już z kilkudziesięcioma klientami i dopracowywane na przestrzeni ostatnich lat, raz rozbudowywane, a raz skracane.

Tak więc z tego tekstu dowiesz się:

• jakie podejście do tworzenia specyfikacji proponuję,
• jakie sekcje w specyfikacji są moim zdaniem ważne,
• jak wypełnić poszczególne sekcje i jak je sformułować,
• wreszcie - jak wygląda wzór takiej specyfikacji, który możesz ściągnąć i używać!

By łatwiej było utrwalić sobie, co powinno znaleźć się w specyfikacji, proponuję zapamiętać ją jako metodę HANSA, czyli:

H - Historia
A - Aktorzy i obiekty
N - Narysuj!
S - Specyfikacja funkcji
A - Aspekty jakości

... A jeśli jesteś tu tylko po specyfikację (z przykładami) i nie chcesz czytać "filozofowania", to dokument jest załączony pod tekstem!

Specyfikacja wymagań i metoda (podejście) HANSA

Specyfikacja ma na celu, oczywiście, opisanie tego, jak ma działać pewne oprogramowanie, które zamówił (lub raczej chce zamówić) u nas klient. W teorii powinien to być ładnie napisany, spójny dokument, który od A do Z będzie wyjaśniał działanie systemu, który następnie przygotują programiści, graficy i odpowiednio skonfigurują administratorzy.

No właśnie, w teorii... Czy jednak jest to możliwe w praktyce?

Tutaj lubię odpowiadać tak, jak odpowiadam na większość pytań związanych z szeroko pojętą inżynierią oprogramowania i metodami zarządzania projektami: to zależy!

Przygotowując specyfikację musimy wziąć pod uwagę następujące kwestie:

• Czy klient dobrze wie, czego tak naprawdę oczekuje (czy też jego wymagania dopiero się formułują)?
• Czy klient jest gotowy poświęcić czas na analizę wymagań i za nią zapłacić (tak, stworzenie specyfikacji wymaga czasu i kosztuje)?
• Czy spodziewam się, że w projekcie będzie następować bardzo dużo zmian (zmiany następują w KAŻDYM projekcie podczas jego realizacji - może być ich jednak mniej lub więcej)?
• Czy klient jest osobą podchodzącą skrupulatnie do dokumentacji i mamy pewność, że wystarczy mu cierpliwości by ją przeczytać?
• Wreszcie - czy my mamy czas na stworzenie precyzyjnej dokumentacji i możemy pozwolić sobie na opóźnienie rozpoczęcia prac programistycznych (a na ile jesteśmy gotowi podjąć ryzyko przyspieszenia prac i związanych z tym nieporozumień)?

Im więcej odpowiedzi TAK w powyższych pytaniach, tym możemy się pokusić o bardziej dokładne przygotowanie dokumentacji. Im więcej NIE, lub "nie wiem" i im bardziej pociągające wydają nam się sformułowania w nawiasach, tym chcemy stworzyć lżejszą, szybszą i mniej skomplikowaną dokumentację.

W praktyce zrobienie lżejszej specyfikacji sprowadza się do dwóch rzeczy:

• usunięcia wszystkich sekcji, które nie są niezbędne
oraz
• wybrania najprostszych sposobów opisu wymagań klienta.

Jako, że sam działam pod ogromną presją czasu, nie uważam, by tworzenie krótszych i prostszych specyfikacji było czymś “gorszym”. Ba - stworzenie krótkiej, jednak relatywnie precyzyjnej specyfikacji jest sztuką, którą niezwykle cenię. Jest nawet szansa, że taką specyfikację klient przeczyta od deski do deski i zrozumie - a o to tak naprawdę nam chodzi.

No dobrze, dobrze... A więc co powinna zawierać dobra specyfikacja?

Po kolei:

1. Historia

Wprowadzenie, które wyjaśni osobie, która nie brała udziału w ustaleniach i nie ma żadnej wcześniejszej wiedzy o systemie, o co tak naprawdę chodzi i jaka jest podstawowa koncepcja stojąca za powstaniem oprogramowania. Wprowadzenie musi być krótkie, lekkostrawne i pozwolić na zrozumienie zakresu prac bez żadnej wcześniejszej wiedzy.

(opcjonalnie) Oprócz samego opisu systemu, w zależności od potrzeb, dodaję tutaj często dwie sekcje: docelowi odbiorcy oraz oczekiwane korzyści biznesowe.

Pierwsza sekcja, dotycząca odbiorców, ma po prostu krótko scharakteryzować typy użytkowników i interesariuszy w systemie. Często są oni na tyle jasno zarysowani w pozostałych elementach specyfikacji, że nie ma potrzeby dodatkowo ich wymieniać, jeśli jednak jest to dość różnorodna grupa, warto wskazać, czego mogą oczekiwać różne osoby od systemu.

Druga sekcja, dotycząca korzyści biznesowych, ma bardzo krótko i ogólnie, przedstawić jakie oczekiwania związane z docelowymi korzyściami ma nasz klient. Czy np. spodziewa się, że system sprawi, iż będzie sprzedawał więcej towaru, który produkuje (nie, drogi czytelniku, nie mam tu na myśli metaamfetaminy), czy ma usprawnić jakiś proces w jego firmie, czy też np. poprawić odbiór marki. Oczywiście, nawet najlepiej przygotowany technicznie system nie może gwarantować osiągnięcia celów biznesowych projektu, które zależą od wielu czynników zewnętrznych, niemniej przedstawienie ich w specyfikacji wymagań pozwala lepiej zrozumieć cel realizacji systemu i to, na jakie aspekty podczas jego tworzenia należy położyć nacisk oraz potraktować priorytetowo. Sekcja ta jednak nie powinna mieć zobowiązującego charakteru - ma po prostu informować o nadziejach, jakie klient wiąże z systemem.

(opcjonalnie) Proces Biznesowy - czyli opis tego, w jaki sposób system będzie zazwyczaj wykorzystywany dla uzyskania korzyści biznesowej przez użytkowników i jak typowy proces interakcji w systemie będzie przebiegał. Ten punkt nie ma na celu przedstawienia szczegółowych wymagań, a tylko pokazać cały proces "z lotu ptaka".

Sekcję tę można przedstawić w formie zwykłego, zwięzłego opisu przyczynowo-skutkowego albo poprzez przedstawienie w formie przypadku użycia na poziomie biznesowym (obie wersje zostały pokazane jako przykłady we wzorze).

2. Aktorzy i obiekty

Ta sekcja, a w zasadzie dwie sekcje, mają przedstawić kto i na czym będzie operował w systemie.

W pierwszej kolejności dobrze jest przedstawić aktorów, czyli po prostu użytkowników lub inne systemy, które będą czynnymi uczestnikami działań. Użytkownikami więc będą np. klienci sklepu internetowego, administrator całego systemu czy sprzedawca, obsługujący sklep. Z drugiej strony aktorem może być również np. system płatności, który potwierdza wykonanie przelewu i wysyła do naszego systemu informację o czasie i kwocie zrealizowanej płatności. Identyfikacja aktorów jest bardzo ważna z punktu widzenia opisywanych później funkcji systemu. By uniknąć nieporozumień, bardzo ważne jest nadanie im spójnych i łatwych do zapamiętania nazw, a także trzymania się ich w całej specyfikacji (np. nie pisać raz "klient", raz "użytkownik", a raz "kupujący", mając na myśli tego samego aktora). To generalnie zasada, której polecam trzymać się w całej specyfikacji - to nie wypracowanie na język polski, tutaj używanie w kółko tych samych terminów jak najbardziej ma sens.

Dalej warto przedstawić obiekty biznesowe (lub obiekty informacyjne), czyli zbiory danych ważne z punktu widzenia operacji w systemie. Mogą to być np. produkty w sklepie internetowym, zamówienia, dane wizytówkowe firm itp. Obiekty służą aktorom do osiągania ich celów i przedstawiają dane przechowywane w systemie. Oczywiście, nie ma sensu wymieniać i opisywać wszystkich rodzajów informacji, które może składować system (to nie jest schemat bazy danych!), a przedstawić jedynie elementy ważne z punktu widzenia wymagań funkcjonalnych.

Jak zwykle, przykłady aktorów i obiektów biznesowych znajdują się we wzorze specyfikacji.

3. Narysuj!

Albo mówiąc bardziej formalnie diagram kontekstu. To po prostu bardzo zwięzła, graficzna reprezentacja naszego systemu, aktorów, niektórych obiektów biznesowych, powiązań pomiędzy nimi i najważniejszych czynności realizowanych w systemie. Diagram musi być prosty i koniecznie mieścić się na jednym ekranie. W niektórych sytuacjach, ten jeden "obrazek" będzie jedynym elementem, z którym rzetelnie zapozna się odbiorca naszej specyfikacji, więc warto by był on czytelny i dobrze obrazował działanie systemu. Powiedzenie "obraz mówi więcej niż tysiąc słów" jest tutaj bardzo adekwatne.

Diagram pełni podobną funkcję jak "Historia" z punktu pierwszego - ma zagwarantować, że każda osoba przeglądająca specyfikację będzie rozumiała czego ona dotyczy i jak z grubsza powinien działać cały system.

Przykład, oczywiście, w specyfikacji.

4. Specyfikacja funkcji

Czyli w zasadzie sedno naszego dokumentu. W tej sekcji opiszemy wszystkie funkcje systemu, które są potrzebne klientowi i który zespół programistów będzie musiał zrealizować. Tak naprawdę szczegółowe opisanie sposobów reprezentacji wymagań funkcjonalnych mogłoby być nie tyle osobnym artykułem, a całą serią artykułów... Niemniej spróbujmy w dużym skrócie omówić jak możemy je opisać.

Na początek możemy jednak przedstawić opcjonalną sekcję, tzn:

(opcjonalnie) Moduły - spis modułów, które występują w systemie wraz z wyjaśnieniem ich roli w systemie. Ta sekcja nie jest konieczna i może być bardziej potrzebna z punktu widzenia zrozumienia założeń architektury systemu niż bezpośrednio samych wymagań. Zazwyczaj tę sekcję pomijam, o ile nie jest to bardzo istotny element pomagający zrozumieć logiczny podział działania systemu, co może mieć miejsce w przypadku szczególnie złożonych systemów.

Wracając jednak do wymagań funkcjonalnych, możemy je reprezentować na wiele mniej lub bardziej formalnych sposobów. Niezależnie od wybranej formy reprezentacji, dobrą praktyką jest nadanie im identyfikatorów (np FR1, FR2 itp.) oraz czytelnych nazw, pozwalających łatwo zrozumieć, co przedstawia dane wymaganie. Można (choć to już reguła, której nie trzymam się kurczowo) od razu po nazwie wymienić aktora lub aktorów, którzy będą uczestniczyć w tym wymaganiu.

Zawsze natomiast powinniśmy trzymać się zasady, że jedno wymaganie dotyczy zrealizowania jednego celu danego aktora - inaczej mówiąc, wymaganie powinno być zwięzłe i konkretne, koncentrując się na jednym działaniu w systemie.

Ja posługuję się zazwyczaj jedną z 3 form reprezentacji wymagań funkcjonalnych:

Forma opisowa

Czyli zwykłe, prozaiczne przedstawienie wymagania w formie opisu na kilka zdań. Bez szczególnej struktury - po prostu opisanie funkcjonalności z perspektywy systemu ("System powinien...") lub użytkownika ("Klient może...") w formie jednego lub kilku zdań. W zależności od poziomu skomplikowania wymagania może to być bardzo krótki opis lub trochę bardziej szczegółowe jego przedstawienie i opisanie sytuacji szczególnych.

Zalety:

• długość adaptuje się do “trudności” wymagania
• nie wymaga dodatkowych umiejętności przy pisaniu
• pozwala opisać mniej standardowe rozwiązania

Wady:

• brak struktury może sprawiać, że będą nieczytelne lub niezrozumiałe
• dużo zależy od samodyscypliny spisującego je analityka
• mogą być nużące w czytaniu dla odbiorcy

Opowieści użytkownika (ang. user stories)

To jedna z bardziej popularnych w ostatnich latach forma prezentacji wymagań, w postaci jednozdaniowych "opowieści" użytkownika ("Jako użytkownik chciałbym..."). Ponieważ zawsze zajmują jedno zdanie, spisuje się je bardzo szybko, niemniej siłą rzeczy nie będą zawierać wszystkich niezbędnych szczegółów. W zależności od przyjętej konwencji, mogą dodatkowo być rozszerzone o "warunki akceptacji", czyli testy, które powinniśmy przeprowadzić, by potwierdzić, że wymaganie zostało spełnione (również w bardzo zwięzłej formie np. "test płatności kartą kredytową").

Zalety:

• krótkie i łatwe w zapisie
• łatwo się czyta
• mają stałą strukturę

Wady:

• nie zawierają szczegółów
• niektóre specyficzne wymagania mogą być trudne do przedstawienia w tej formie

Przypadki użycia (ang. use cases)

To najbardziej rozbudowana i najlepiej ustrukturalizowana forma wymagań, przedstawiająca je jako listę kroków, które wykonuje aktor, wraz z odpowiedziami systemu. Dobrze napisany przypadek użycia jest precyzyjny, zawiera listę rozszerzeń, które opisują sytuacje wyjątkowe i... jest dość czasochłonny w zapisaniu.

Zalety:

• precyzyjne i szczegółowe
• zrozumiałe nawet dla osoby, która widzi je pierwszy raz
• mają stałą strukturę

Wady:

• czasochłonne
• wymagają znajomości reguł ich zapisu i pewnej wprawy w ich stosowaniu, by pozostały precyzyjne i czytelne
• mogą być nużące w czytaniu dla odbiorcy
• czy już wspominałem, że ich spisywanie jest czasochłonne?

Którą więc formę wybrać? To już, oczywiście, kwestia indywidualnych preferencji. Jeśli nie mamy w tym dużego doświadczenia, proponuję zacząć od pierwszej lub drugiej. Trzecia jest dobra w szczególnie “poważnych” systemach, gdzie mamy czas na stworzenie szczegółowych wymagań i bardzo skrupulatnie rozliczamy się z nich z klientem.

Przykłady wszystkich trzech form, jak zwykle, we wzorze.

Niezależnie natomiast od przyjętej konwencji i formy, należy pamiętać, że wymagania funkcjonalne mają opisywać tylko to, co system ma robić, a nie to JAK ma to robić. Do tej ostatniej kwestii dochodzimy właśnie w punkcie 5.

5. Aspekty jakości

To ostatnia sekcja, którą umieszczam w specyfikacji i dotyczy ona tzw wymagań pozafunkcjonalnych (zwanych też przez niektórych “niefunkcjonalnymi”, jednak zdecydowanie bardziej odpowiada mi ta pierwsza nazwa). Dotyczy ona wszystkich kwestii, które nie są funkcjami systemu, ale są ważne dla klienta, takich jak: szybkość działania, bezpieczeństwo, użyteczność interfejsu itp. Oczywiście, ta sekcja może a nawet powinna być też być dość rozbudowana. Co więcej, identyfikacja wymagań pozafunkcjonalnych z klientem bywa dużo trudniejsza niż wymagań funkcjonalnych, bo najczęściej to na naszej roli (analityka) spoczywa ciężar uświadomienia klienta, czego tak naprawdę w kwestii jakości potrzebuje.

Brak identyfikacji tych kwestii jest najczęstszym powodem problemów z odbiorem, bo klient "myślał, że to będzie działać szybciej..." albo "myślał, że to będzie miało mniejsze wymagania serwerowe...".

Na szczęście, z pomocą w identyfikacji wymagań, których może potrzebować klient, przychodzą standardy, które prezentują gotowe listy charakterystyk, o których warto porozmawiać i dopytać w trakcie analizy wymagań.

Ja staram się stosować standard ISO 25010, który wskazuje 8 obszarów wymagań pozafunkcjonalnych, a w każdym obszarze wskazuje jeszcze konkretne podcharakterystyki. To ponownie temat na osobny artykuł, niemniej ogólnodostępnych materiałów o standardzie ISO 25010 nie brakuje i można bez trudu wesprzeć się nimi podczas rozmów z klientem, tak by nakierować go i siebie na istotne wymagania jakościowe.

Co ważne, nie należy spisywać wszystkich, w tym zupełnie nieistotnych wymagań jakościowych, byle tylko wypełnić "checklistę" ze standardu ISO. Spisujemy tylko te wymagania, które mają znaczenie.

Przy spisywaniu wymagań pozafunkcjonalnych, staram się trzymać zasady SMART, takiej samej, jak przy ustalaniu celów w projekcie, czyli:

• S (Specific/Simple) - skonkretyzowane, czyli jedno wymaganie pozafunkcjonalne ma dotyczyć tylko jednego aspektu oprogramowania. Ma być ponadto sformułowane możliwie prosto i jednoznacznie;
• M (Measurable) - mierzalne, czyli takie, które możemy jednoznacznie zweryfikować, czy zostały spełnione czy nie. Przykład niemierzalnego wymagania to: "lista produktów ma się ładować szybko". Przykład tego samego wymagania, sformułowanego w sposób mierzalny to: "lista produktów ma się ładować średnio w nie więcej niż 2 sekundy, przy następujących założeniach...". Mierzalność, to moim zdaniem najważniejsza cecha dobrze zdefiniowanego wymagania pozafunkcjonalnego. Brak mierzalności w wymaganiach pozafunkcjonalnych, będzie prowadził do dyskusji i konfliktów z klientem w czasie odbioru, w czasie których następuje często sytuacja w której mamy "słowo przeciwko słowu";
• A (Achievable) - osiągalne, czyli takie, który możemy realnie, biorąc pod uwagę ograniczenia w projekcie, dostarczyć w naszym systemie. Tutaj należy zwrócić uwagę między innymi na to, czy mamy sprzęt i technologię, by przygotować rozwiązania w takiej wersji, jak wyobraża sobie klient;
• R (Relevant) - mające znaczenie, czyli takie, które nie są zdefiniowane po to "by były", tylko które rzeczywiście mają znaczenie dla finalnej jakości systemu. Nie ma więc sensu definiować szczególnych wymagań dotyczących szybkości w aplikacji, która będzie operowała na statycznych danych wśród małej grupy użytkowników. Jednak np. wymagania dotyczące wyglądu mogą być bardzo istotne, jeśli projekt który tworzymy, to gra komputerowa;
• T (Timed) - określone w czasie, jednak tej cechy najczęściej nie trzeba jawnie deklarować, ponieważ czas realizacji wymagań pozafunkcjonalnych jest zazwyczaj równy terminowi realizacji projektu. Niemniej, są sytuacje (szczególnie, jeśli system oddajemy w etapach), w których poszczególne wymagania będziemy chcieli zrealizować wcześniej lub później i wtedy warto zawrzeć taką dodatkową uwagę przy wymaganiu. Ponieważ cała specyfikacja dokumentuje cechy aplikacji, a nie harmonogram jej realizacji, czas realizacji wymagania pozafunkcjonalnego też powinien być określony nie w datach, a względem (wcześniej/później) innych wymagań. Jednak w zdecydowanej większości wymagań pozafunkcjonalnych nie określam jawnie czasu ich realizacji.

I... to już wszystkie sekcje, którymi posługuje się w podejściu HANSA.

Garść uwag końcowych i podsumowanie

Mimo, że sam opis tego podejścia wyszedł dłuższy, niż się spodziewałem, jest to tak naprawdę tylko bardzo powierzchowne przedstawienie tematu specyfikacji... Niemniej, dokładnie taki był cel - przedstawić podejście, które można zastosować od ręki i użyć jako punkt wyjścia na potrzeby współpracy z klientem. Sam przed laty szukałem podobnego "przewodnika" ze wzorem dokumentacji - liczę więc, że przyda się on do zmniejszenia liczby potencjalnych pól do konfliktu z klientami.

Podsumowując, najważniejsze kwestie, które dotyczą takiej dokumentacji, to:

• specyfikacja jest dla klienta i zespołu IT,
• czas poświęcony na jej tworzenie powinien być adekwatny do zaangażowania klienta w jej przygotowanie (również finansowego),
• dokumentacja musi być przede wszystkim zrozumiała i czytelna - kłania się zasada KISS (Keep It Simple, Stupid!),
• ważne jest wprowadzenie i diagram kontekstu, który zrozumie nawet osoba, która pierwszy raz usłyszała o projekcie,
• dokumentację adaptujemy do potrzeb projektu - nigdy nie staramy się "na siłę" zachować przyjętego szablonu, gdyż praktyka jest ważniejsza niż konwencja!
• ze względu na ewolucję wymagań i świadomości klienta, dokumentacja będzie się z czasem zmieniać - zarówno przed rozpoczęciem projektu jak i już w trakcie jego realizacji,
• by zachować prostotę, możesz zastosować podejście HANSA (Historia, Aktorzy i Obiekty, Narysuj!, Specyfikacja funkcji, Aspekty jakości).

Piotr "Hans" Miklosik

Podziękowania dla:

• Jakub Rojek - który jest współautorem wzoru specyfikacji i pomagał w edycji tekstu,
• Tomasz Boczarski - za przygotowanie ilustracji,
• Joanna Twardowska - za korektę tekstu.