Jakie diagramy warto zrobić w dokumentacji?

Z tego co widzę to wiele osób boi się diagramów. Boją się ich na tyle, że nie projektują ich wcale. A szkoda bo dokumentacja wiele traci.

Bo dobry diagram znaczy więcej niż 1000 słów.

Podejrzewam, że brak diagramów w dokumentacji wynika, z:

  • strachu, że zaprojektujemy go niezgodnie ze standardami;
  • braku znajomości „typów diagramów” – nie wiadomo co diagram ma pokazać.

Dziś „rozpracuję” te rzeczy, żeby ułatwić Ci start w świecie diagramów.


Boję się, że zrobię diagram niezgodny ze standardami 😨


I co się takiego złego stanie? 🙂 Wiem, że pewnie teraz podpadnę „straniżkom notacji UML”.
FYI: diagramy projektuje się w notacji UML.

Ale uważam, że w diagram jest narzędziem KOMUNIKACJI. Jeśli przekazujesz na przykład dany proces w diagramie i jest on zrozumiały dla czytelnika, ale jest niezgodny z notacją UML – to według mnie nie szkodzi. Osiągnąłeś cel diagramu – czytelnik rozumie co chciałeś powiedzieć.

To jest tak jak z językiem angielskim – często staramy się powiedzieć coś w odpowiednim czasie, z odpowiednią gramatyką, a przy tym zaczynamy się gubić i sens naszej wypowiedzi ucieka.

Lepiej wyszłoby nam gdybyśmy powiedzieli zdanie z kilkoma błedami, ale pomimo to zostali zrozumieni.

Analogicznie jest z diagramami.


Jakie diagramy warto narysować?


Kolejny dylemat, przed którymi stoją początkujący analitycy. Diagramów jest tak wiele, że można wpaść w tzw. „paraliż analityczny”. Czyli nie wiadomo od czego zacząć.

Oczywiście powinieneś dobrać diagram na podstawie tego co chcesz przekazać odbiorcy dokumentacji.

Podpowiem Ci co ja robię zazwyczaj. Podejrzewam, że ten sposób sprawdzi się w wiekszości przypadków projektowych (ale pewnie nie we wszystkich).

1. Diagram przypadków użycia – zacznij od niego. Jest stosunkowo łatwy w zaprojektowaniu. Pozwoli Ci poznać skalę projektu. Będziesz w stanie ocenić czy projekt, z którym masz do czynienia jest duży czy raczej mały.

2. Diagram czynności – kolejnie zaprojektowałbym diagram czynności. Nie służy on stricte do projektowania procesów, ale pozwoli Ci „ułożyć sobie w głowie” najważniejsze przepływy, sekwencję zdarzeń w projekcie. Skrótem myślowym byłoby to, że zaprojektujemy diagramem czynności procesy w naszym projekcie.

3. Diagram klas – bardzo przydatny diagram, który pomoże Ci zbudować „system nomenklatury”, którą będziesz używał z klientem. Nie ma chyba ważniejszej rzeczy niż jednoznaczność pojęć, które występują w projekcie. Nie myl proszę tego diagramu z diagramem struktury bazy danych w projekcie. Ten diagram z pewnością doceni zespół realizacyjny – programiści, testerzy, bazodanowcy.

4. Diagram stanów (maszyny stanowej) – świetny diagram do zaprezentowania zmiany stanów naszych „obiektów” w projekcie. Diagram często jest uzupełnieniem diagrami czynności. W diagramie stanów oprócz zmiany stanów wypisujemy również zdarzenia, które zachodzą w systemie. Pozwoli to lepiej zrozumieć co się dzieje na przykład z daną umową lub zamówieniem. Pomoże programistom lepiej ułożyć strukturę kodu i dać odpowiednie nazwy metod pod zdarzenia.

5. Diagram sieci projektu – diagram, który nie tłumaczy zakresu, ale jest dobrym wstępem pod harmonogram projektu. Pozwala na ułożenie zadań w kolejności sekwencyjnej – dzięki temu wiemy, które z nich możemy realizować równolegle. Wyznaczymy z niego również ścieżkę krytyczną projektu. Przyda się w ostatniej fazie analizy, gdzie już mamy ukończoną dokumentację.

Polecam Ci stosować pierwsze cztery diagramy w swoich projektach – diagram przypadków użycia, diagram czynności, diagram klas i diagram stanów. Na pewno wpłynął na lepsze zrozumienie zakresu między Tobą i klientem.

Nie bój się popełniać błędy podczas rysowania diagramów. Lepszy diagram z niepoprawną notacją niż brak zrozumienia zakresu między Tobą i klientem.

Właśnie takie podejście rekomenduję w moim kursie o tworzeniu dokumentacji – Dokumentacja.Pro, czyli:

  • komunikacja diagramowa ponad poprawną notację;
  • jeśli się wie jak – używanie poprawnej notacji;
  • jeśli się nie wie jak – zarządzanie ryzykiem z tytułu użyciem błędnej notacji.


Na koniec mam do Ciebie pytanie…

Dlaczego do tej pory nie projektowałeś diagramów? A jeśli je projektujesz jakie statystycznie najczęściej?


Dziękuję, że przeczytałeś ❤️

Pssst... przygotowałem dla Ciebie kilka prezentów - wybierz co Ci się przyda! 👍

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany.

Witryna wykorzystuje Akismet, aby ograniczyć spam. Dowiedz się więcej jak przetwarzane są dane komentarzy.