Dokumentowanie oprogramowania

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 🙌.