Lubisz tradycyjny polski bigos? Spokojnie, to nie jest blog kulinarny. Szablon specyfikacji wymagań i potem sposób w jaki jest on uzupełniany czasami kojarzy mi się z tą popularną potrawą. Powstaje w podobny sposób i jest tak samo ciężki.
Z tego artykułu dowiesz się dlaczego nie polecam modelu à la bigos i jak ten problem można rozwiązać korzystając ze sprawdzonych wzorców.
Chaos, czyli specyfikacja IT jak bigos
Bigos ma kilka cech charakterystycznych:
- wszystko wrzuca się do jednego garnka,
- każdy robi go po swojemu,
- jest raczej ciężkostrawny.
Bywa, że według podobnego przepisu przygotowywane są specyfikacje wymagań.
Ktoś tworzy dokument Word i zaczyna opisywać wymagania. Najpierw trochę logiki systemu, do tego dorzuca opis pól i reguł walidacji, między to wkleja specyfikację integracji, a wszystko okrasza przewijającymi się tu i tam nawiązaniami do graficznego interfejsu użytkownika.
Powstaje idealny bigos. Wszystko razem. Według uznania autora. Ciężko to się czyta i jeszcze ciężej utrzymuje.
Rozwiązaniem są sprawdzone od lat modele, które na co dzień wykorzystują programiści. Wystarczy zaaplikować je do szablonu specyfikacji wymagań i potem konsekwentnie pilnować podążania za standardem.
Model szablonu specyfikacji wymagań z podziałem na warstwy
Programiści już dawno temu zorientowali się, że podejście na zasadzie: „napiszmy cały program w jednym pliku i jakoś to będzie” się nie sprawdza. Jest to do zrobienia, tylko potem wprowadzenie jakiejkolwiek zmiany jest czasochłonne i generuje lawinę błędów. A przekazanie takiego kodu komuś innemu jest niemożliwe.
Uczmy się od programistów
Już w latach 70-tych XX w. pojawiła się pierwsza koncepcja podziału odpowiedzialności poszczególnych warstw systemu pod nazwą MVC (Model-View-Controler).
We wzorcu tym każdy z komponentów ma inną odpowiedzialność:
- Model jest odpowiedzialny za strukturę danych i logikę aplikacji w oderwaniu od graficznego interfejsu użytkownika.
- Widok (view) odpowiada za prezentację informacji np. w formie wykresów czy tabel.
- Kontroler (controler) odbiera informacje od interfesju użytkownika i konwertuje je na format zrozumiały przez Model.
Od razu wiadomo gdzie szukać jakich fragmentów kodu. Jeżeli więc programista chce np. zmienić sposób prezentacji danych na wykresie, to robi to tylko w Widoku.
Podobnych schematów jest wiele. Dzięki nim struktura kodu jest zrozumiała dla każdego w projekcie, a utrzymanie i wprowadzanie zmian staje się dużo prostsze.
Teraz przełóżmy to na szablon specyfikacji wymagań.
Budowanie specyfikacji wymagań według szablonu
Jest wiele narzędzi do zbierania i opisywania wymagań (tu znajdziesz ich ponad 75). Załóżmy jednak, że chcesz lub musisz opisać je w dokumencie tekstowym.
Zanim powstanie pierwsza linijka opisu systemu zastanów się jakie warstwy chcesz opisywać. Może to być np. model danych, reguły biznesowe, procesy, interfejs użytkownika itd.
Zawsze możesz dołożyć kolejną warstwę już w trakcie pisania.
Wyraźnie wydziel te warstwy w dokumencie (np. jako osobne rozdziały) i opisując wymagania stosuj kilka podstawowych zasad:
- Korzystaj ze wspólnego słownika pojęć. Wyrażenia osłownikowane możesz pisać z dużej litery, dzięki czemu będziesz wiedzieć kiedy jest mowa o dokładnie tym Systemie czy Użytkowniku.
- Nigdy nie mieszaj zagadnień pomiędzy warstwami. Nie opisuj interfejsu użytkownika w rozdziale o modelu danych. Nie kopiuj tych samych reguł biznesowych do opisu różnych procesów itd.
- Stosuj referencje odporne na zmiany struktury dokumentu. Często przydaje się np. nawiązanie w części UI do reguł biznesowych. Zastosuj wtedy odnośnik, ale nie do numeru rozdziału czy strony, tylko do unikalnego identyfikatora danej reguły lub rozdziału.
- Jeżeli jakiś fragment pojawia się dwa lub więcej razy to zapisz go w jednym miejscu i stosuj referencję. Nigdy nie kopiuj dwa razy tych samych treści, bo to generuje błędy przy aktualizowaniu dokumentu.
- Poszczególne rozdziały sortuj w taki sposób aby łatwo było nawigować po dokumencie. Na przykład obiekty posortuj alfabetycznie, a procesy biznesowe według kolejności w jakiej są najczęściej wywoływane.
- Jeżeli któraś z „warstw” jest zbyt duża to możesz ją wydzielić do osobnego dokumentu.
Dokumentacja budowana zgodnie z tymi regułami ma czytelną strukturę. Jest po prostu lekkostrawna.
Jeżeli pojawią się zmiany, a na pewno się pojawią, to wiesz od razu gdzie wprowadzić modyfikacje. Edytowanie dokumentu jest proste i przyjemne. I co ważne, nie generuje lawiny błędów.
Szablon i przykład opisu wymagań (do pobrania)
Przygotowałem listę rozdziałów, które możesz wykorzystać do budowania własnego szablonu. Jest tam też przykład zastosowania takiego modelu w praktyce.
Plik znajdziesz tradycyjnie na stronie z materiałami do pobrania (nr 10 na liście).
Tak samo jak programiści testują swój kod, tak samo dokumentacja wymagań powinna być testowana. W tym artykule podaję gotowy przepis na przeprowadzenie procesu kontroli jakości dokumentacji.
Dobra struktura i trzymanie się zasad to nie wszystko. Ważne jest czytelne i precyzyjne opisywanie wymagań. W tym wpisie zebrałem kilka pomocnych zasad do zastosowania w każdym projekcie.