Szablony dokumentów projektowych dla metodyk klasycznych

Transkrypt

1 Szablony dokumentów projektowych dla metodyk klasycznych Autor Jarosław Kuchta Centrum Doskonałości Naukowej Infrastruktury Wytwarzania Aplikacji (CD NIWA). Projekt współfinansowany z Europejskiego Funduszu Rozwoju Regionalnego w ramach Programu Operacyjnego Innowacyjna Gospodarka. Dotacje na innowacje Politechnika Gdańska, ul. Gabriela Narutowicza 11/12, Gdańsk 1/11

2 Spis treści 1. Wprowadzenie Ogólny szablon dokumentu Strona tytułowa Metryczka dokumentu Historia zmian Spis treści Streszczenie Numeracja stron Specyfikacja elementu Dokumenty fazy przygotowania Wizja systemu Słownik pojęć Specyfikacja wymagań Dokumenty fazy analitycznej Model przypadków użycia Model klas Dokumenty fazy projektowania Projekt architektury systemu Projekt logiki biznesowej Projekt interfejsu użytkownika Projekt struktury danych Dokumenty fazy implementacji Specyfikacja implementacji Dokumenty fazy testowania Projekt testów Raport z testów...10 Załączniki szablony dokumentów /11

3 1. Wprowadzenie Niniejszy dokument zawiera zestawienie szablonów typowych dokumentów projektowych dla projektów informatycznych wytwarzanych metodami klasycznymi. W tym dokumencie zawarto objaśnienia dokumentów, ich elementów oraz sposobu ich wykorzystania. Właściwe szablony dokumentów zostały podane w załącznikach. 2. Ogólny szablon dokumentu Każdy dokument projektowy powinien w sposób jednoznaczny identyfikować przedstawioną w nim treść. Powinien ułatwiać czytelnikowi zorientowanie się w strukturze dokumentu i odnalezienie interesującej go treści. Dlatego powinien zawierać takie elementy jak: stronę tytułową, metryczkę dokumentu, opcjonalną historię zmian, spis treści, opcjonalne streszczenie, numerację stron, opcjonalnie nagłówki stron, opcjonalnie indeks. Dokumenty projektowe zawierają zwykły, opisowy tekst oraz diagramy i specyfikacje. Zarówno diagramy, jak i specyfikacje przedstawiają te same elementy projektowe (modele) w różny sposób Strona tytułowa Strona tytułowa powinna być pierwszą stroną dokumentu i nie powinna zawierać innych informacji niż: logo / identyfikator / nazwę projektu, którego dotyczy dokument tytuł dokumentu, opcjonalnie podtytuł, opcjonalnie wersję dokumentu lub datę sporządzenia, nazwiska wszystkich autorów, opcjonalnie identyfikator / logo organizacji, która jest właścicielem dokumentu, opcjonalnie identyfikatory / loga organizacji, które wspierają projekt. Uwagi: Umieszczenie identyfikatora lub loga organizacji właścicielskiej i organizacji wspierających powinno być uregulowane zasadami wewnętrznymi organizacji. Logo / identyfikator / nazwa projektu powinny być umieszczone w nagłówku każdej strony dokumentu, a identyfikatory lub loga organizacji w stopce na stronie tytułowej. Tytuł dokumentu powinien być pisany największą czcionką spośród wszystkich użytych na stronie tytułowej, a w szczególności większą od podtytułu. Tytuł dokumentu musi odpowiadać treści dokumentu. W razie niemożności odróżnienia jednego dokumentu od drugiego po tytule, trzeba podać podtytuł. Wersję dokumentu lub datę ostatniej redakcji dokumentu podaje się zawsze, gdy w projekcie może wystąpić kilka wersji tego samego dokumentu. W przypadku pierwszej wersji dokumentu można pominąć numer wersji na stronie tytułowej pod warunkiem podania jej w metryczce dokumentu. 3/11

4 W przypadku kilku autorów dokumentu na pierwszej pozycji podaje się nazwisko autora głównego, który jest odpowiedzialny za dokument. Pozostałych autorów można wymieniać w dowolnej kolejności. Zawsze trzeba podawać pełne imię i nazwisko każdego autora (bez ew. tytułów osobistych). Skracanie imion do inicjałów jest niedopuszczalne nawet w przypadku długiej listy autorów Metryczka dokumentu Metryczka dokumentu jest krótką informacją o dokumencie. Powinna być umieszczona zaraz za stroną tytułową (może być na odwrocie strony tytułowej). Powinna zawierać takie informacje jak: identyfikator / nazwę projektu, którego dotyczy dokument, opcjonalnie nazwisko kierownika projektu, identyfikator / nazwę dokumentu, opcjonalnie typ dokumentu, numer wersji, datę pierwszego utworzenia, datę ostatniej modyfikacji, nazwisko osoby odpowiedzialnej (głównego autora), opcjonalnie nazwisko autora ostatniej modyfikacji, opcjonalnie nazwisko redaktora (jeśli nie jest autorem dokumentu), opcjonalnie datę ostatniej redakcji, opcjonalnie nazwisko osoby, która sprawdziła dokument, opcjonalnie datę sprawdzenia dokumentu, opcjonalnie nazwisko osoby, która zatwierdziła dokument, opcjonalnie datę zatwierdzenia dokumentu, opcjonalnie status dokumentu. Uwagi: Identyfikator dokumentu umożliwia jednoznaczne rozpoznanie dokumentu w repozytorium dokumentów organizacji i powinien być zgodny z systemem identyfikacji dokumentów w organizacji właścicielskiej. Nazwa dokumentu może, ale nie musi być identyczna z tytułem dokumentu. W odróżnieniu od identyfikatora dokumentu jest nazwą opisową, czytelną i łatwą do zapamiętania przez człowieka. Typ dokumentu podaje się, jeśli nie można rozróżnić zawartości dokumentu po nazwie. Numer wersji dokumentu powinien się składać z sekwencji liczb całkowitych (nieujemnych) oddzielonych kropkami. Pierwsza liczba powinna identyfikować duże wersje projektu (licząc od 1), pozostałe powinny identyfikować większe i mniejsze wydania produktu, ostatnia liczba powinna reprezentować kolejne modyfikacje dokumentu. Redakcję od modyfikacji autorskich dokumentu odróżnia to, czy zmiany dotyczą formy czy treści dokumentu. Poprawki ortograficzne, interpunkcyjne czy gramatyczne nie są traktowane jako zmiana treści dokumentu. Identyfikowanie osoby sprawdzającej dokument i osoby zatwierdzającej dokument zależy od systemu zarządzania dokumentami w organizacji. Jeżeli edycja, redakcja, sprawdzanie lub zatwierdzanie dokumentu trwają kilka dni, to podaje się datę zakończenia danego działania. Status dokumentu powinien być zgodny ze zdefiniowanym cyklem życia dokumentu w organizacji. 4/11

5 2.3. Historia zmian W przypadku kolejnej wersji dokumentu zalecane jest przedstawienie historii zmian dokumentu. W historii podaje się krótko opisy kolejnych wersji zawierające: numer wersji, datę zmiany, nazwisko autora zmiany, krótki opis tego, co zostało zmienione, opcjonalnie nazwiska redaktora, osoby sprawdzającej, osoby zatwierdzającej, opcjonalnie nowy status dokumentu. Historia zmian powinna być podana zaraz za metryczką dokumentu Spis treści Spis treści powinien być zatytułowany. Tytuły rozdziałów i podrozdziałów powinny być ponumerowane hierarchicznie Streszczenie Streszczenie powinno być krótkie (1-2 zdaniowe) i jedynie wyjaśniać rolę dokumentu. Streszczenie nie jest obowiązkowe Numeracja stron Numer każdej strony, jak i liczba wszystkich stron w dokumencie powinny być pokazywane na stopce każdej strony z wyjątkiem strony tytułowej i strony z metryczką dokumentu Specyfikacja elementu Specyfikacja elementu jest to tabelka, która opisuje element projektowy. Powinna ona zawierać identyfikator referencyjny elementu, jego nazwę, krótki opis oraz właściwości istotne w kontekście dokumentu. Jeden element może występować w wielu dokumentach. Przykład tabelki specyfikacji przedstawia Rys. 1. REFID_001 Opis: Nazwa elementu Krótki opis tekstowy Właściwość 1: Specyfikacja właściwości 1 Właściwość 2: Specyfikacja właściwości Powiązania: Referencje (hiperłącza) do innych elementów Rys. 1. Przykład specyfikacji elementu projektowego Identyfikator referencyjny jest jednoznacznym (w danym kontekście) identyfikatorem elementu składającym się z pewnego skrótu literowego związanego z typem elementu oraz numeru kolejnego. Identyfikator referencyjny elementu (w odróżnieniu od jego nazwy) jest niezmienny w całym projekcie. Ważnym elementem specyfikacji elementu są referencje (hiperłącza) do innych elementów projektowych podawane w formie REFID Nazwa elementu. Umożliwiają one śledzenie powiązań między elementami, np. powiązań różnych elementów z wymaganiami. 5/11

6 3. Dokumenty fazy przygotowania W fazie przygotowania, oprócz dokumentów czysto organizacyjnych (zlecenie projektowe plan, harmonogram) stosuje się następujące dokumenty inżynierskie: wizja systemu specyfikacja wymagań systemowych słownik pojęć 3.1. Wizja systemu Wizja systemu może być umieszczona w osobnym dokumencie lub na początku specyfikacji wymagań. Rolą wizji systemu jest krótkie przedstawienie istoty systemu w sposób zrozumiały dla laika. W odróżnieniu od innych dokumentów nie zawiera ona specyfikacji elementów projektowych, a jedynie tekst opisowy i opcjonalnie tzw. rich picture, który na jednym rysunku obrazowo przedstawia istotę problemu Słownik pojęć Słownik pojęć jest tabelą prezentującą najważniejsze pojęcia występujące w projekcie, w różnych dokumentach. Często stosuje się słownik pojęć w postaci bardzo uproszczonej, dołączanej do specyfikacji wymagań Specyfikacja wymagań Specyfikacja wymagań stanowi podstawę dla wszystkich działań inżynierskich, a w polityce TQM również dla planowania. Zawiera ona takie elementy jak: określenie źródeł wymagań, określenie celów projektu, określenie kontekstu systemu, opcjonalnie koncepcję architektury systemu, specyfikacje wymagań funkcjonalnych, specyfikacje wymagań niefunkcjonalnych, opcjonalnie specyfikacje sytuacji wyjątkowych, kryteria akceptacyjne. Źródła wymagań dzieli się na osobowe i nieosobowe. Źródłami osobowymi są tzw. interesariusze (ang. stakeholders). Są to osoby, grupy osób i organizacje, które są zainteresowane w realizacji projektu. Wśród interesariuszy koniecznie umieszcza się klientów, użytkowników i zespół projektowy. Źródłami nieosobowymi mogą być akty prawne, normatywy, standardy formalne i nieformalne, specyfikacje innych systemów, które muszą być brane pod uwagę. Cele projektu mogą być biznesowe i funkcjonalne. Cele biznesowe określają korzyści, które klienci lub użytkownicy mogą odnieść z zastosowania systemu. Cele funkcjonalne opisują główne funkcjonalności, którymi system ma wspierać osiąganie celów funkcjonalnych. Kontekst systemu zawiera wyszczególnienie użytkowników systemu i ewentualnie zewnętrznych systemów, które będą współpracować z systemem. Posłuży on później do definiowania aktorów w modelu przypadków użycia. Koncepcję architektury systemu przedstawia się w przypadku systemu złożonego, zwłaszcza rozproszonego. Pokazuje się na niej najważniejsze komponenty lub podsystemy. Posłuży ona później do opracowania szczegółowego projektu architektury systemu. 6/11

7 Wymagania funkcjonalne stanowią główną część specyfikacji wymagań. Ze względu na dużą liczbę wymagań funkcjonalnych są one dzielone na grupy zorganizowane według ról użytkowników lub celów funkcjonalnych. Wymagania niefunkcjonalne to są wymagania na dane, wymagania jakościowe, wymagania sprzętowe, programowe i inne. Wymagania na dane opisują główne komponenty danych (takie jak np. cennik, faktura). Wymagania jakościowe dzieli się na grupy (np. wymagania dot. niezawodności, wydajności, elastyczności, użyteczności) i opisuje jak najbardziej precyzyjnie (zwłaszcza liczbowo). Wymagania sprzętowe opisują konfigurację komponentów sprzętowych prezentowanych w koncepcji architektury. Wymagania programowe opisują konfigurację programową (np. środowisko systemowe) projektowanego systemu. Sytuacje wyjątkowe to sytuacje nadzwyczajne (nie mieszczące się w standardowych scenariuszach działania użytkowników), sytuacje krytyczne (mogące doprowadzić do załamania systemu) i sytuacje awaryjne (gdy załamanie systemu już nastąpiło). Umieszczenie sytuacji wyjątkowych w specyfikacji wymagań służy do jej uzupełnienia o te wymagania, które są znane klientowi, lecz nie wymieniane jawnie, albo są nie znane klientowi, lecz wymagane ze względu na standardy jakościowe (formalne i nieformalne). Dlatego sytuacje wyjątkowe wiążą się ściśle z wymaganiami jakościowymi i funkcjonalnymi. Kryteria akceptacyjne określają warunki akceptacji systemu przez klienta, np. warunki testowania. Ich uzgodnienie z klientem na początku projektu pozwoli uniknąć nieporozumień na jego końcu. 4. Dokumenty fazy analitycznej W fazie analizy opracowuje się model przypadków użycia i model klas Model przypadków użycia Model przypadków użycia jest sposobem na analizę wymagań funkcjonalnych. Efektem tej analizy powinna być weryfikacja i ewentualna korekta i uzupełnienie specyfikacji wymagań. Z drugiej strony model przypadków użycia stanowi podstawę do projektowania interfejsu użytkownika. Dokument pt. Model przypadków użycia powinien zawierać: specyfikacje aktorów, diagram hierarchii aktorów, diagram (lub diagramy) przypadków użycia, specyfikacje poszczególnych przypadków użycia, opcjonalnie modele interakcji do nietrywialnych scenariuszy przypadków użycia. Aktorzy stanowią formalizacje ról użytkowników i systemów zewnętrznych. Definiuje się ich na podstawie opisu kontekstu systemu ze specyfikacji wymagań, analizuje i uzupełnia o aktorów abstrakcyjnych. Aktor abstrakcyjny to taki, który nie występuje bezpośrednio w otoczeniu systemu, lecz reprezentuje zbiór funkcjonalności wspólnych dla kilku innych, rzeczywistych aktorów. Diagram hierarchii aktorów prezentuje relacje generalizacji-specjalizacji między aktorami. Aktor wyspecjalizowany (znajdujący się niżej w hierarchii) ma wszystkie te możliwości, które ma aktor uogólniony (znajdujący się wyżej w hierarchii), a oprócz tego ma swoje własne, wyspecjalizowane możliwości. Wprowadzenie aktorów uogólnionych umożliwia jednoznaczną analizę scenariuszy tych przypadków użycia, które dotyczą kilku aktorów. Możliwości aktorów są reprezentowane przez przypadki użycia. Przypadki użycia są definiowane na postawie wymagań funkcjonalnych. Każde wymaganie funkcjonalne powinno być odwzorowane w jakiś przypadek użycia (przynajmniej jeden). Pomiędzy przypadkami użycia definiuje się re- 7/11

8 lacje zawierania (ang. include) i rozszerzania (ang. extend) oraz relacje generalizacji-specjalizacji. Każdy przypadek użycia musi być powiązany z jakimś aktorem (bezpośrednio lub pośrednio). Mogą być przypadki, w których uczestniczy więcej aktorów niż jeden. Należy wówczas odróżnić aktora głównego, który inicjuje przypadek użycia, od innych aktorów. Odróżnienie będzie potrzebne do analizy scenariuszy przypadku użycia. Specyfikacja przypadku użycia zawiera określenia: aktora, którego dotyczy (aktora głównego), opcjonalnie innych aktorów, warunków początkowych, warunków końcowych, scenariusza realizacji przypadku użycia (w postaci listy kolejnych kroków). Jeśli w modelu występują przypadki użycia, których realizacja wymaga złożonego scenariusza (lub kilku scenariuszy), to do dokumentu dołącza się modele interakcji (współdziałania lub sekwencji), na których umieszcza się aktora (aktorów) i główne komponenty systemu. Diagramy interakcji służą do poprawy zrozumienia szczegółów między klientem a zespołem projektowym Model klas Model klas stosowany w analizie jest środkiem do zrozumienia i odkrywania struktury statycznej dziedziny problemu. Za pomocą klas definiuje i modeluje byty występujące w rzeczywistości. Dokument pt. Model klas powinien zawierać: diagram (lub diagramy) klas, specyfikacje poszczególnych klas, opcjonalnie modele stanów dla wybranych klas. W czasie analizy specyfikuje się tylko klasy wynikające bezpośrednio ze specyfikacji wymagań, ze słownika pojęć (jeśli został sporządzony) oraz z innych źródeł: z rozmów z klientami i ekspertami, z wiedzy dziedzinowej. W specyfikacji definiuje się właściwości klas (cechy informacyjne) w postaci nazwy i typu. W analizie nie określa się widoczności właściwości (wszystkie są publiczne). Typy określa się w miarę ogólnie (np. number, integer, real, currency zamiast int, double, decimal). Opcjonalnie określa się możliwości klas, ale również w sposób ogólny (nie jako konkretne funkcje). 5. Dokumenty fazy projektowania W fazie projektowania sporządza się następujące dokumenty: projekt architektury systemu, projekt logiki biznesowej, projekt interfejsu użytkownika, projekt struktury danych Projekt architektury systemu Projekt architektury systemu stanowi podstawę do opracowania pozostałych projektów. Projekt architektury systemu przedstawia: koncepcję architektury systemu, 8/11

9 schemat architektury systemu, specyfikacje głównych komponentów (podsystemów), uzupełnioną specyfikację wymagań jakościowych Schemat architektury systemu tworzy się na podstawie koncepcji architektury ew. zarysowanej w specyfikacji wymagań i dokładniej opisanej w tym dokumencie. Tu stosuje się diagram komponentów, ew. diagram wdrożenia. Przedstawiając architekturę wielowarstwową stosuje się grupowanie komponentów (pakiety). Definiuje się podsystemy (czyli komponenty złożone) i główne komponenty. Definiuje się też interfejsy między komponentami (bez szczegółów). Przy architekturze wielowarstwowej definiuje się główne komponenty w każdej z warstw. Specyfikację wymagań jakościowych uzupełnia się o te wymagania, które się pojawiły w czasie projektowania. Wymagania się precyzuje, przypisuje do komponentów i opisuje ich sposób realizacji (dla deweloperów) Projekt logiki biznesowej Projekt logiki biznesowej opisuje komponenty realizujące logikę biznesową (tj. logikę wymaganą i opisywaną przez dziedzinę problemu). Stosuje się tu model klas ze specyficznymi założeniami: Definiuje się klasy grupujące operacje biznesowe. Operacje te są wywoływane z interfejsu użytkownika, ew. udostępniane innym komponentom. W szczególności definiuje się klasy komponentowe, grupujące obiekty klas encyjnych. Określa się widoczność właściwości i precyzuje ich typy. Definiuje się konkretne operacje i precyzuje ich parametry oraz typy wyniku Projekt interfejsu użytkownika Projekt interfejsu użytkownika opisuje schemat interfejsu wraz z głównymi komponentami IU. Projekt zawiera: koncepcję implementacji interfejsu użytkownika, analizę cech użytkowników, schemat układu interfejsu wraz ze specyfikacją paneli, specyfikację komend, specyfikację menu i innych elementów sterujących, specyfikację formularzy, opcjonalnie specyfikację raportów. Analiza cech użytkowników opisuje ich indywidualne cechy, takie jak wiek, doświadczenie, umiejętności, upodobania, ograniczenia. Cechy użytkowników mogą, lecz nie muszą być przypisane do ich ról. Cechy stanowią podstawę do szczegółowych decyzji projektowych. Schemat interfejsu przedstawia układ paneli wraz z ich rolą i zawartością. Komendy stanową logiczne elementy łączące elementy nawigacyjne (sterujące) interfejsu użytkownika z operacjami oferowanymi przez komponenty logiki biznesowej. Menu, paski przycisków narzędziowych, gesty myszy to elementy nawigacyjne i sterujące. Ich aktywacja powoduje wykonanie komend. Specyfikacja formularzy określa dane przekazywane za ich pomocą oraz pokazuje schematycznie ich wygląd. 9/11

10 5.4. Projekt struktury danych Projekt struktury danych jest oparty na modelu analitycznym klas biznesowych. Identyfikuje się klasy trwałe (wymagające przechowywania danych) i opisuje sposób przechowywania ich danych. Projekt struktury danych zawiera: schemat i specyfikację klas encyjnych, schemat i specyfikację komponentów danych, schemat i specyfikację struktury bazy danych, oszacowanie rozmiaru bazy danych. Klasy encyjne reprezentują indywidualne obiekty danych, na których operują komponenty biznesowej. Do ich przedstawienia używa się diagramu ERD. Komponenty danych to klasy, które pośredniczą między bazą danych a komponentami biznesowymi. Zawierają definicje właściwości z funkcjami dostępowymi do danych. Funkcje dostępowe umożliwiają tworzenie, zapisywanie, pobieranie i aktualizację encji danych. Encje mają odwzorowanie w strukturze bazy danych w tabelach i kwerendach. Do ich opisu używa się specyfikacji podobnych do specyfikacji klas, z tym że zamiast właściwości klas definiuje się kolumny tabel. Na końcu przedstawia się oszacowanie rozmiaru bazy danych. Oszacowanie robi się na podstawie średniego rozmiaru rekordów i szacowanej liczby początkowej oraz przyrostu liczby rekordów. Uwzględnia się narzut na indeksowanie tabel. 6. Dokumenty fazy implementacji Każda klasa implementacyjna powinna mieć dokumentację wygenerowaną na podstawie kodu źródłowego. Ponadto sporządza się specyfikację implementacji ułatwiającą zorientowanie się w strukturze kodu Specyfikacja implementacji Specyfikacja implementacji powinna zawierać: schemat struktury fizycznej kodu (plików, folderów, pakietów) schemat struktury modułów, specyfikacje modułów. 7. Dokumenty fazy testowania W fazie testowania sporządza się projekt testów i raport z testów Projekt testów Projekt testów opisuje przypadki testowe tworzone na podstawie przypadków użycia i ich scenariuszy Raport z testów Raport z testów przedstawia: opis testów (kto, kiedy i co testował), wyniki testów (z odwołaniem do zaprojektowanych przypadków testowych), ogólnie wnioski i zalecenia do modyfikacji. 10/11

11 Załączniki szablony dokumentów 1. Specyfikacja wymagań systemowych 2. Model przypadków użycia 3. Model klasy 4. Projekt architektury systemu 5. Projekt logiki biznesowej 6. Projekt interfejsu użytkownika 7. Projekt struktury danych 8. Specyfikacja implementacji 9. Raport z testów 11/11