Szablon dokumentacji projektowej

Należy opisać przeznaczenie systemu. Na przykład system obsługi biblioteki może dotyczyć biblioteki w AGH lub biblioteki w domu kultury. Skale tych systemów są nieporównywalne.

(użytkownicy, właściciele, nabywcy systemu, pracownicy obsługi technicznej, użytkownicy wewnętrzni, zewnętrzni)

Należy krótko (np.: w tabeli) wyliczyć podstawowe cele stawiane systemowi przez poszczególnych użytkowników. Porównać sposób ich realizacji w aktualnym systemie (np.: manualnym) i systemie proponowanym. Należy nadać im priorytet.

Celem:

• Użytkownika - jest zazwyczaj pewna funkcjonalność lub wydajność
• Właściciela - np.: użycie technologii,platform, implementacja funkcji odróżniających od konkurencji, rozbudowane procedury konfiguracji/instalacji, czas realizacji
• Zespołu odpowiedzialnego za rozwój - użycie konkretnych technologii (doświadczenie)

W notacji UML - granicami systemu są Aktorzy

Aktorem może być:

• Użytkownik
• Inny system
• Czas (dla procesów lub zadań uruchamianych samoczynnie w wybranych momentach czasu)

Diagram pokazuje system oraz aktorów. Odpowiednik diagramu kontekstowego DFD. Np.: Obrazek z sieci

Wyliczenie bez szczegółowych opisów, można podzielić na funkcje dostępne dla grup użytkowników.

Ten rozdział można zilustrować diagramem czynności (activity diagram) pokazującym typowe sekwencje działań wykonywanych w systemie. Poszczególnym czynnościom można nadać identyfikatory przypadków użycia.

Ideą jest,aby diagram czynności pokazywał pewien większy proces, obejmujący różne aktywności (także wykonywane manualnie). Np.:

1. Czytelnik wyszukuje książkę w katalogu i sprawdza jej dostępność i lokalizację na półce
2. Czytelnik bierze książkę z półki i zanosi do stanowiska bibliotekarza
3. Bibliotekarz rejestruje wypożyczenie

Pierwsza czynność jest kandydatem na przypadek użycia Wyszukaj w katalogu; druga: jest manualna i nie jest przypadkiem użycia systemu; trzecia to: Zarejestruj wypożyczenie.

2-5 stron

• Klasy zidentyfikowane w dziedzinie problemu, opis atrybutów
• Diagramy klas (relacje)
• Diagramy stanów (dla wybranych klas)
• Słownik pojęć

Zazwyczaj w dziedzinie problemu identyfikuje się klasy odpowiadające:

• obiektom fizycznym (paczka, osoba, samochód, samolot)
• zdarzeniom lub stanom (przyjęcie towaru, odlot, wypożyczenie)
• abstrakcyjnym pojęciom charakterystycznym dla dziedziny (PESEL, kolor, świadek)

Słownik pojęć powinien definiować podstawowe pojęcia (termin – znaczenie), którymi będziemy posługiwać się w dokumentacji. Najlepiej w formie tabeli. Słownik może przyrastać w miarę sporządzania dokumentacji.

2-5 stron

Specyfikacja wymagań definiuje wymagania stawiane systemowi w postaci przypadków użycia. Przypadki użycia mogą być zgrupowane w pakiety.

• Ogólny diagram przypadków użycia
• Definicje przypadków użycia (należy przyjąć w miarę wyczerpujący szablon wskazujący aktorów, udziałowców, prewarunki, postwarunki, scenariusze itd.)

Przypadek użycia powinien zostać zdefiniowany zgodnie z przedstawionym dalej szablonem. Ponieważ dążymy do zdefiniowania wszystkich przypadków użycia, należy starać się ograniczyć ich liczbę i złożoność relacji. Dla podanych tematów należy oczekiwać 5-20 przypadków użycia. Zbyt mała liczba (np.: 3) świadczy o ogólnikowym potraktowaniu tematu, zbyt duża o nadmiernym zagłębieniu w szczegóły. W przypadku dużej liczby przypadków użycia typu Nowy, Modyfikuj, Usuń należy starać się scalić je w jeden (Definiuj) przedstawiając pozostałe jako przebiegi alternatywne.

brak ograniczeń objętościowych, wystarczy przedstawić specyfikacje dla 5 przypadków użycia

• Wyliczenie warstw (np.: architektura trójwarstwowa model-widok-kontroler)
• Lub wyliczenie podstawowych komponentów będących odrębnymi programami (nadawca-odbiorca, klient-serwer). Zamodelowanie ich jako klas z odpowiednim zestawem metod.
• Specyfikacja interfejsu pomiędzy komponentami (np.: format wymiany danych pomiędzy nadawcą i odbiorcą – opcjonalnie).

W przypadku większości systemów wystarcza określenie, że są wykonywane w trójwarstwowej architekturze. Dla systemów złożonych z samodzielnych programów (np.: komunikator korzystający z pośrednictwa serwera konieczne jest zdefiniowanie interfejsu komunikacyjnego.

W opisie architektury należy określić

• platformę implementacji systemu (komponentów systemu) lub/oraz
• sposób integracji systemu (usługi sieciowe, procesy.

1 – 5 stron

Rozdział opcjonalny Jeżeli występuje, powinien identyfikować:

• podstawowe klasy występujące w systemie (atrybuty, metody, związki, diagramy stanów klas).
• opisywać ich zachowanie za pomocą diagramów sekwencji lub współdziałania

Opis powinien pomijać celowo szczegóły implementacji. Dobrym uzasadnieniem dla tworzenia tego opisu jest aplikacja, która jest projektowana dla wielu platform. W docelowym projekcie dla danej platformy abstrakcyjne elementy zostaną odwzorowane w konkretne elementy projektu (np.: interfejs MFC, interfejs HTML, interfejs XWindows, itp.

Dla serwisów internetowych zrealizowanych w architekturze trójwarstwowej rozdział ten można pominąć. Projekt oprogramowania zapewni w takim przypadku odpowiedni poziom szczegółowości.

brak ograniczeń na objętość

Projekt systemu jest realizowany dla konkretnej platformy (języka programowania zapewniającego podstawowy zestaw klas, biblioteki, architektury systemu, itd.). W zasadzie rozdział ten powinien być największym objętościowo fragmentem. Jeżeli system składa się z niezależnych modułów (klient-serwer, nadawca-odbiorca) należy dla każdego z nich podać osobny projekt.

W projekcie należy określić platformę implementacji komponentu. Java, .NET, PHP, Oracle, MySQL. Może to również zostać określone przy definicji architektury systemu.

Zawartość:

• Definicje klas (atrybuty, metody):
  • klas odpowiedzialnych za prezentację danych: dialogów, stron HTML
  • klas odpowiedzialnych za przetwarzanie, skryptów
  • klas odpowiedzialnych za składowanie danych (baza danych)
• Związki miedzy klasami (także związki z klasami występującymi w analizie dziedziny)
• Opis zachowania dla przypadków użycia (diagramy sekwencji lub współdziałania) odpowiadający scenariuszom.

Identyfikując klasy (zwłaszcza dla serwisów internetowych) należy pamiętać, że ta część dokumentacji powinna odpowiadać na pytanie:

• jakie strony może utworzyć dany skrypt
• jakie operacje wykonuje na bazie danych

Mimo, że strony są generowane dynamicznie, należy potraktować je jak klasy.
Mimo, że kwerendy są również generowane dynamicznie, należy potraktować je jako metody klasy BazaDanych (lub jednej z klas modelu). Takie podejście pozwala oszacować wielkość i złożoność interfejsu użytkownika oraz stopień złożoności operacji na bazie danych.

Objętość: każdy przypadek użycia powinien zostać zdefiniowany za pomocą odpowiedniego diagramu interakcji. Klasy (z atrybutami i metodami) oraz ich związki powinny zostać również zdefiniowane. W miarę możliwości zestaw powiązanych zależnościami klas należy umieszczać przed diagramem interakcji. opis klas w tabelach, 5 diagramów związków klas, 5 diagramów dla zachowania

• Dla klas interfejsu użytkownika należy dołączyć ich projekt (typu zrzuty ekranu lub schematy interfejsu w Visio).
• Schemat może być uzupełniony diagramem stanów pokazującym sposób nawigacji po interfejsie użytkownika.
• Formularze, strony powinny być opisane identyfikatorami klas.
• Jeżeli formularz lub strona pokazuje listę elementów, oczekuje się, że na diagramie struktury pokazana zostanie agregacja pomiędzy klasą strony i klasą odpowiadającą elementowi.

należy przedstawić najbardziej interesujące diagramy; można pominąć elementy typu menu, lista opcji

• Schemat bazy danych jako diagram ERD
• Specyfikacja kwerend (metody klasy są kwerendami, należy podać ich specyfikację)

1 diagram + tabela ze specyfikacjami kwerend