Dokumentacja jest kluczowa dla skutecznego zarządzania, utrzymania i rozwijania systemu. Dobra dokumentacja ułatwia zrozumienie funkcji, interfejsów i ogólnej architektury systemu co ułatwia współpracę między zespołami a także usprawnia onboarding nowych pracowników. Dobra dokumentacja oznacza oszczędność czasu (i pieniędzy), który w innym przypadku musiałby być przeznaczony na spotkania, ustalenia itd.
Cechy dobrej dokumentacji
- zrozumiała - napisana w przystępny sposób bez zawiłych i skomplikowanych terminów technicznych.
- aktualna - regularnie aktualizowana.
- kompletna - wszystkie istotne funkcje i elementy systemu powinny być dokładnie opisane w dokumentacji, powinna zawierać informacje na temat instalacji, konfiguracji, używania, zwalczania problemów oraz utrzymania systemu.
- łatwo dostępna i dobrze zorganizowana - użytkownicy powinni mieć możliwość łatwego znalezienia potrzebnych informacji.
Co warto umieścić w dokumentacji
Dokumentacja powinna zawierać przede wszystkim wiedzę biznesową systemu. Zwykle tą część dokumentacji utrzymują analitycy biznesowi i product ownerzy, gdyż to oni wiedzą o zmianach jako pierwsi. Techniczne aspekty systemu również powinny znaleźć się w dokumentacji. Oczywiście można być zwolennikiem samo dokumentującego się kodu ale często może być to za mało. Dlatego warto aby zespół, głównie developerzy postarali się o aktualizowanie dokumentacji w tym kontekście np. w postaci ADR (Architecture Decision Record).
Przykładowe elementy, które warto umieścić w dokumentacji:
- Funkcje i odpowiedzialności (zarys biznesowy)
Za co mikroserwis jest odpowiedzialny, jakie dane przetwarza i jakie pełni funkcje w kontekście całego systemu, kto jest opiekunem. - Stack technologiczny
Opis systemu w kontekście użytych technologii, aktualizowany na bieżąco wraz z wyjaśnieniem dlaczego wybraliśmy takie technologie a nie inne. Warto pomyśleć o utrzymywaniu ADR (Architecture Decision Record), który mógłby być nawet przechowywany w repozytorium kodu. - Środowiska
Spis środowisk (np. INT, PREP, PROD itd). - Repozytorium
Spis wszystkich repozytoriów git rozwijanych w ramach danego podsystemu. - Dokumentacja API
Zbiór informacji opisujących funkcje, zasady i sposoby korzystania z danego interfejsu programistycznego. Jej istotną rolą jest umożliwienie developerom zrozumienia jak prawidłowo korzystać z API, jakie są dostępne funkcje, jakie parametry przyjmują żądania oraz jakich odpowiedzi możemy się spodziewać.
Powinna być możliwość pobrania aktualnej specyfikacji API w formacie yaml/json zgodnej z standardem openapi (wsdl w przypadku SOAP). Pomocnym narzędziem może się okazać swagger. - Interakcje z innymi systemami
Opis integracji z innymi systemami w tym wymagane protokoły komunikacyjne. - Instrukcje instalacji i konfiguracji
Instrukcja zawierająca ważne informacje o instalacji czy też uruchomieniu aplikacji w szczególności uruchomieniu na lokalnym środowisku developerskim co pozwoli szybko wdrożyć się w system nowemu developerowi. Idealnie aby każde repo posiadało README.md, w którym będzie opisane jak uruchomić system lokalnie. - Instrukcje użytkowania
Opis jak korzystać z różnych funkcji i narzędzi systemu. - Proces CI/CD
Chcemy tutaj opisać proces jaki zachodzi od zmiany kodu przez developera w ramach jakiejś funkcjonalności po wdrożenie zmian na produkcję. - Changelog
Chcemy dokumentować wszystkie zmiany w pliku changelog najlepiej przechowywanym w repozytorium kodu. Przykład pliku changelog. - Testowanie
W jaki sposób podchodzimy do testowania mikroserwisu, jakie testy wykonujemy. - Konwencje
Informacje dla developerów, jeżeli chodzi o konwencje kodowania (np. pliki checkstyle) lub inne ważne informacje. - Awarie
Rejestr awarii zawierający opis co się wydarzyło, kiedy, co było przyczyną i jak udało się naprawić oraz inne przydatne informacje. - Inne
Inne przydatne informacje np. informacje kontaktowe dla wsparcia technicznego.
Oczywiście jest to tylko ogólna propozycja tego co mogłoby się znaleźć w dokumentacji. W zależności od specyfiki projektu może wyglądać to inaczej.
Podsumowanie
Inwestycja w szczegółową i zrozumiałą dokumentację oprogramowania to inwestycja w przyszłość - oszczędza czas, zasoby i zwiększa efektywność pracy zespołu. Jeżeli masz jakieś ciekawe spostrzeżenia na ten temat komentarz będzie mile widziany 🙌.
