Dokumentacja techniczna – się robi się!

Zastanawiałeś się kiedyś jak ma wyglądać dobra dokumentacja techniczna? Czy sama myśl o napisaniu dokumentacji powoduje u Ciebie odruch wymiotny? Jak to dziadostwo napisać?

Wielokrotnie przeżywałem tego typu trudności. Chaos w mojej głowie był przelewany na papier co siłą rzeczy powodowało chaotyczne rozdziały dokumentacji projektowej. Ciągle nurtowały mnie pytania na jaki poziom szczegółowości wchodzić w dokumencie technicznym. Czy rysować diagramy UML? Jeśli tak, to jakie? Więcej pytań niż odpowiedzi. Już sama myśl o UMLu powoduje uśmiech na mojej twarzy. Jeszcze nikt nigdy nie pokazał mi błędu w moich diagramach. Czy jestem aż tak dobry? Czy może nikt tego nie czyta lub nie wnika czy „dzida” w diagramie powinna być zamknięta, czy strzałka z pudełka do pudełka ma być rysowana linią przerywaną. A grot? Otwarty czy zamknięty? Znajomo brzmi, prawda? 🙂

C4 model

Odpowiedź na te wszystkie pytania znalazłem w książce Simona BrownaSoftware Architecture for Developers„. Rekomenduję każdemu programiście i każdemu architektowi zapoznanie się z tą pozycją. Mimo, że Simon Brown nie odkrywa Ameryki, to w bardzo ciekawy sposób prostuje światopogląd na temat przedstawiania architektury. A oto jego recepta. 4 magiczne słowa: Context, Container, Component, Class. C4 model!

Zastanów się, kto będzie odbiorcą dokumentacji, którą piszesz. Czy człowiek z biznesu? Pewnie trochę tak. Czy nowy programista, który dołączył do zespołu? Na 100% tak. A może tester, który chce poznać jak wygląda aplikacja? A może w końcu administrator przygotowujący infrastrukturę? To też! Idąc tym tokiem myślenia Simon Brown porównuje naszą dokumentację do mapy google, na której przedstawiasz ogólnie temat, a później zoomując się coraz niżej wchodzisz w szczegóły.

20140824-c4

Context

Pierwszy etap to przedstawienie otoczenia naszego systemu. To narysowanie schematu blokowego, w którym nasza aplikacja jest tylko jednym klockiem. Cała reszta to interakcja z innymi systemami dziedzinowymi. Pozwala to na wyrobienie poglądu na temat aplikacji i całego ekosystemu. Głównym adresatem tego rozdziału są ludzie z biznesu, ale również nowi programiści.

Container

Kolejny etap w naszej dokumentacji to przejście na widok kontenera. Pokazanie jak aplikacja wygląda z punktu widzenia administratora. W jaki sposób nasz system się instaluje na kontenerze servletów, ale również jak powinna wyglądać konfiguracja. W tym przypadku głównym adresatem są administratorzy.

Component

W momencie, gdy przedstawiliśmy kontekst aplikacji i sposób jej instalacji czas zajrzeć w głąb. Rozdział ten powinien zawierać opis komponentów systemu i ich interakcji między sobą. Gdy stosujesz Domain Driven Design – wystarczy opisać poszczególne agregaty. Jest to rozdział dedykowany programistom i testerom.

Classes

Ostatni element to opis klas. Jest to element opcjonalny. Ja osobiście nie do końca się zgadzam z koncepcją opisywania klas i rysowania diagramu klas. Jest to zbędny nakład pracy. Kod ewaluuje, jest ciągle refaktoryzowany. Wg mnie dobra klasa dokumentuje się sama. Czy jest to więc rozdział do pominięcia? Nie! W tym rozdziale osobiście opisuję jak mam ułożone klasy i pakiety, jaki rodzaj architektury jest w projekcie oraz przedstawiam diagram bazy danych.

We wspomnianej wyżej książce Simon Brown pokazuje dokładny układ dokumentacji technicznej, czyli 14 obowiązkowych punktów do wypełnienia tekstem. Jakich? Zajrzyj do książki „Software Architecture for Developers” i napisz swoją idealną dokumentację techniczną. Mi się udało! Opisałem 14 punktów i pokazałem to koledze, który wdrażał się w mój projekt. Nie miał ani jednego pytania i skwitował: „Najlepsza dokumentacja jaką czytałem”.

Teraz Twoja kolej! Tworzenie dokumentacji już nie musi być nudne!

Źródła obrazków:

  1. http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html

About the author

piotr.filipowicz

View all posts