> ## Content Index
> Fetch the complete content index at: https://lsdev.pl/llms.txt
> Use this file to discover other available public pages before exploring further.

# Dokumentowanie oprogramowania
- URL: https://lsdev.pl/posts/dokumentowanie-oprogramowania/
- Published: 2024-01-31T13:15:47.000Z
- Updated: 2024-01-31T13:15:47.000Z
- Author: Łukasz Sakowicz
- Tags: Software, Architecture, Programming, #Import 2026-08-18 22:07

**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](https://bulldogjob.pl/readme/czym-jest-architecture-decision-record?ref=lsdev.pl) (*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](https://bulldogjob.pl/readme/czym-jest-architecture-decision-record?ref=lsdev.pl) (*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](https://swagger.io/?ref=lsdev.pl).
- **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](https://gist.github.com/juampynr/4c18214a8eb554084e21d6e288a18a2c?ref=lsdev.pl) 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 🙌.