Audyt architektury: analiza dokumentacji

W tym wpisie i w następnych oddalam się nieco od żywego oprogramowania, idąc w kierunku często zaniedbywanych, choć naprawdę niezbędnych, składników projektu. Na początek trywialna sprawa: dokumentacja…

Analiza dokumentacji

Motywacja/Cel
Analiza dokumentacji ma na celu głównie sprawdzenie jej kompletności i aktualności. Są to bardzo ważne aspekty, ponieważ dokumentacja jest podstawą dalszego rozwoju oprogramowania oraz leży u podstaw kształtowania procesów w projekcie.

Metoda
Analiza dokumentacji nie jest niczym innym jak “ręcznym” sprawdzeniem wszelkich dokumentów, które mają wpływ na kształtowanie oprogramowania i całego projektu. W szczególności należy poświęcić uwagę następującym zagadnieniom:

  • Czy dokumentacja jest aktualna? Czy jest w razie potrzeby na bieżąco aktualizowana?
  • Czy dokumentacja jest kompletna? Przez kompletność rozumiem tutaj to, że wszystkie fazy tworzenia aplikacji, wszystkie elementy natury biznesowej jak i elementy właściwego oprogramowania są opisane w sposób wystarczający i pozbawiony luk. W szczególności ważne jest zdefiniowanie zależności między warstwami aplikacji i innymi obiektami oraz sprecyzowanie używanych pojęć (glosariusz!)
  • Czy dokumentacja jest łatwo dostępna dla wszystkich uczestników projektu? Powinna ona znadjować się w z góry zdefiniowanym miejscu (katalog na serwerze, wiki itp.), które z łatwością jest dostępne dla wszystkich zainteresowanych. W idealnej sytuacji sposób przechowywania dokmentacji powinien zapewniać mechanizm wersjonowania.
  • Czy forma dokumentacji jest jednorodna w projekcie? Szablony dokumentacji usprawniają jej tworzenie i “konsumpcję” w ramach projektu.
    • (Kontr)przykład
      W jednym z projektów dokumentacja różnych modułów miała zupełnie różną formę, zakres i inną definicję tych samych pojęć. Doprowadziło to do kompletnego chaosu w implementacji i chociaż techniczna struktura aplikacji była we wszystkich modułach taka sama, to funkcjonalność rozkładała się zupełnie inaczej na różne warstwy. Dochodzący do tego brak wspónego rozumienia tak samo brzmiących nazw i terminów (brak glosariusza dla całego projektu) doskonale utrudniał komunikację pomiędzy architektami i programistami, prowadząc do zwiększonego nakładu pracy.

Dodaj komentarz