Inżynieria oprogramowania

Dokumentowanie wytwarzania

w cyklu rozwojowym systemu

informatycznego

Slajd 2

Plan wykładu

• Dwa podstawowe rodzaje dokumentacji
• Klasyfikacja w zależności od cyklu

rozwojowego, w którym została
wytworzona, adresata itp.

• Co zapewniają standardy dokumentacji?

Slajd 3

Dwa podstawowe

rodzaje

dokumentacji

Slajd 4

Dokumentacja

Producenta

Producenta

(opisuje szczegółowo

proces wytwórczy i

rozwiązania wykorzystane

do stworzenia systemu)

Użytkow

Użytkow

nika

nika

(opisuje system jako

produkt, ukierunkowana na

ułatwienie korzystania z

oprogramowania)

Kierownictwo Zespół projektowy

(projektanci, programiści)

Użytkownicy systemuAdministratorzy

Slajd 5

Dokumentacja

• Dokumentacja jest integralną częścią

systemu i powinna powstawać równolegle z
procesem wytwórczym oprogramowania

• Często jakość dokumentacji jest dobrym

miernikiem stopnia dojrzałości procesu
tworzenia oprogramowania w organizacji

• Opracowanie dobrej dokumentacji pozwala

uniknąć wielu problemów na etapie
wdrożenia i następnie rzeczywistego
wykorzystania systemu

Slajd 6

Dokumentacja producenta 1/2

W trakcie trwania przedsięwzięcia

powstają następujące dokumenty:

•

dokumentacja procesu

dokumentacja procesu

produkcji

oprogramowania

•

dokumentacja techniczna

dokumentacja techniczna

opisująca

wytworzony produkt

Slajd 7

Dokumentacja producenta 2/2

Dokumentacja procesu obejmuje:

•

Plany, szacunki, harmonogramy

Plany, szacunki, harmonogramy

- dokumenty tworzone

przez kierownictwo przedsięwzięcia jako propozycje;
odbiorcami ich są przełożeni wyższego szczebla; po
zaakceptowaniu dokumenty tego typu pełnią rolę poleceń dla
wykonawców

•

Raporty

Raporty

- dokumenty (przygotowywane przez kierowników

dla przełożonych) opisujące przebieg i rezultaty prac

•

Standardy

Standardy

- dokumenty opisujące pożądany sposób realizacji

•

Dokumenty robocze

Dokumenty robocze

- rozmaite dokumenty zawierające

propozycje rozwiązań tworzone przez członków zespołu;
zaakceptowane mogą stać się standardami, raportami,
planami, ...

•

Komunikaty

Komunikaty

- rozmaite, z reguły krótkie dokumenty służące

do wymiany informacji pomiędzy członkami zespołu

Slajd 8

Dokumentacja techniczna 1/2

• Zawiera dokładny opis systemu (

projekt

+ kod + testy + oszacowanie
niezawodności...

); przeznaczona jest

zwykle wyłącznie dla producenta

• Dokumentacja techniczna przed oddaniem

oprogramowania do eksploatacji powinna
być poddana weryfikacji celem
wyeliminowania błędów i nieścisłości

Slajd 9

Dokumentacja techniczna 2/2

Istotne jest wypracowanie w firmie standardów

dokumentacji technicznej:

• procesów wytwarzania dokumentacji

: tworzenia

wstępnej wersji dokumentów, wygładzania, drukowania,
powielania, oprawiania, wprowadzania zmian w
istniejących dokumentach, zatwierdzania; konieczne
jest ścisłe określenie odpowiedzialnych za to osób

• treści i formy dokumentów

: strona tytułowa, spis

treści, budowa rozdziałów, podrozdziałów i sekcji,
indeks, słownik

• sposobu dostępu do dokumentacji:

niezbędne jest

stworzenie rodzaju biblioteki dokumentów
technicznych, z zapewnieniem sprawnego dostępu do
dowolnego dokumentu

Slajd 10

Dokumentacja użytkownika 1/2

•

Opis funkcjonalny

Opis funkcjonalny

- wstępna część

dokumentacji opisująca w sposób zwarty
przeznaczenie i główne możliwości systemu;
może być wykorzystywana do pierwszego
zapoznania się z oprogramowaniem

•

Podręcznik użytkownika

Podręcznik użytkownika

- przeznaczony

głównie dla początkujących użytkowników;
powinien zawierać podstawowe informacje
niezbędne do korzystania z systemu
(najlepiej na podstwie przykładów) oraz
odnośniki do bardziej szczegółowych
informacji

Slajd 11

Dokumentacja użytkownika 2/2

•

Kompletny opis systemu

Kompletny opis systemu

- przeznaczony

głównie dla doświadczonych użytkowników;
opisujący całą funkcjonalność oraz ograniczenia
systemu, zawierający opisy formatów danych,
możliwych błędów, ...

•

Instrukcja instalacji

Instrukcja instalacji

- przeznaczona głównie dla

administratora, zawiera procedurę instalacyjną

•

Podręcznik administratora

Podręcznik administratora

- opisuje

możliwości zmian konfiguracji dostępne bez
ingerencji twórców systemu oraz sposoby
udostępninia systemu użytkownikom końcowym;
tworzenie kopii zapasowych, ...

Slajd 12

Dokumentacja użytkownika 1/2

Czynniki wpływające na

postrzeganie i akceptację

dokumentacji przez użytkowników:

• czytelna

struktura dokumentu

• zachowywanie

standardów

• sposób

przekazu informacji

:

– stosowanie formy aktywnej i zwracanie się

bezpośrednio do użytkownika

– bezwzględna poprawność gramatyczna i

ortograficzna

– zwięzła forma (krótkie zdania zawierające

pojedyncze fakty; rozsądnej długości akapity)

Slajd 13

Dokumentacja użytkownika

– jasność wypowiedzi

, eliminacja

dwuznaczności

precyzyjne definicje

używanych terminów (najlepiej zebrane
dodatkowo w słowniczku)

– powtarzanie trudnych opisów

(w

przypadku kluczowych kwestii dopuszczalne
jest powtórzenie opisu w kilku miejscach)

– stosowanie tytułów

(podtytułów) sekcji,

wyliczeń i wyróżnień

– zrozumiałe odwołania

do innych części

dokumentacji

Slajd 14

Klasyfikacja w zależności od cyklu rozwojowego,
w którym została wytworzona, adresata itp

Slajd 15

Klasyfikacja w zależności od cyklu

rozwojowego, w którym została

wytworzona, adresata itp. 1/2

• Techniczna

(projektowa, warsztatowa)

• Planistyczna

(specyfikacyjna - co?,

realizacyjna – jak?)

• Sprawozdawcza

(rozliczenie zużycia

zasobów)

• Analityczna

(oszacowanie efektywności

procesu projektowo-produkcyjnego,
statystyki technologiczne)

Slajd 16

Klasyfikacja dokumentacji w zależności od cyklu

rozwojowego, w którym została wytworzona,

adresata itp. 2/2

• Jakościowa

(dokumentacja kontroli projektu

- np..: protokoły z kontroli międzyfazowych,
badań, testów, dokumentacja kontrolna
dokumentacji eksploatacyjnej)

• Adaptacyjna

(protokoły uzgodnień,

protokoły zatwierdzeń)

• Eksploatacyjna

(informacyjna,

operatorsko/administratorska,
konserwatorska, użytkownika, specjalna,
raporty dla producenta)

Slajd 17

Co zapewniają standardy
dokumentacji?

Slajd 18

Standardy dokumentacji

zapewniają:1/2

• Planowanie

nakładów pracy, kosztów i

terminów z racjonalnie niskim ryzykiem
pomyłek,

• Kontrolowanie

cyklu rozwojowego pod

względem zgodności z harmonogramem i
planowanym budżetem oraz ocenę
ewentualnych modyfikacji w tym zakresie

• Jednolite przedstawianie

dokumentacji

technicznej oraz kontrolowanie zgodności
produktów powstających w różnych fazach
cyklu rozwojowego z założeniami

Slajd 19

Standardy dokumentacji

zapewniają:2/2

• Stosowanie

jednolitych narzędzi

analitycznych, projektowych i
programistycznych do komputerowego
wspomagania prac

• Zmianę wykonawcy

po zakończeniu

dowolnej fazy bez konieczności
powtarzania całego cyklu rozwojowego od
początku

Slajd 20

O czym był wykład?

• Dwa podstawowe rodzaje dokumentacji
• Klasyfikacja w zależności od cyklu

rozwojowego, w którym została
wytworzona, adresata itp.

• Co zapewniają standardy dokumentacji?