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