Dokumentacja techniczna oprogramowania: 5 zasad i gotowe szablony (README, ADR, runbook)

Dobra dokumentacja techniczna odpowiada na konkretne pytania konkretnych ludzi: jak uruchomić projekt, jak go wdrożyć, dlaczego coś zrobiono tak, a nie inaczej, i co zrobić, gdy w nocy padnie produkcja. Żeby ją taką zrobić, wystarczy pięć zasad i kilka sprawdzonych szablonów dokumentacji technicznej — oba elementy znajdziesz poniżej.

Artykuł dotyczy dokumentacji oprogramowania i systemów IT. Jeśli szukasz wzorów dokumentacji technicznej dla budownictwa lub maszyn (np. DTR), zasady pisania będą podobne, ale wymagania formalne określają tam przepisy i normy branżowe.

Czym jest dokumentacja techniczna i po co ją pisać

Dokumentacja techniczna to zbiór materiałów opisujących, jak system działa, jak jest zbudowany i jak go obsługiwać. W projekcie IT obejmuje zwykle:

• opis architektury i głównych komponentów,
• instrukcje instalacji, konfiguracji i wdrożenia,
• dokumentację API i formatów danych,
• zapis decyzji projektowych i ich uzasadnień,
• procedury operacyjne: monitoring, kopie zapasowe, reagowanie na awarie,
• historię zmian (changelog, release notes).

Najważniejszy argument za dokumentacją to ryzyko związane z wiedzą „w głowach”. Jeśli tylko jedna osoba wie, jak odtworzyć serwer z kopii albo dlaczego cache czyści się co 17 minut, projekt ma niski bus factor. Dokumentacja skraca też wdrażanie nowych osób i ogranicza liczbę pytań, które odrywają doświadczonych programistów od pracy.

Zasada 1: zacznij od czytelnika i jego zadania

Zanim napiszesz pierwsze zdanie, odpowiedz na dwa pytania: kto to przeczyta i co ma potem umieć zrobić. Nowy programista potrzebuje uruchomić projekt lokalnie w godzinę. Administrator potrzebuje wiedzieć, które porty otworzyć i gdzie są logi. Integrator potrzebuje listy endpointów i przykładów zapytań.

Praktyczne konsekwencje:

• jeden dokument = jeden odbiorca i jeden cel; nie mieszaj samouczka z referencją konfiguracji,
• zakładaj minimalną wiedzę wstępną i wypisz ją wprost („Wymagania: Docker 24+, dostęp do VPN”),
• pisz w trybie rozkazującym w instrukcjach („Uruchom”, „Skopiuj”), a nie opisowo („Następnie należy dokonać uruchomienia…”).

Zasada 2: rozdziel typy treści (model Diátaxis)

Najczęstszy problem dokumentacji to wymieszanie wszystkiego na jednej stronie. Model Diátaxis porządkuje treści w czterech kategoriach, z których każda ma inny cel:

Gdy w instrukcji krok po kroku zaczynasz tłumaczyć historię decyzji, przenieś ten fragment do osobnego dokumentu typu „wyjaśnienie” i podlinkuj. Instrukcja pozostanie krótka i wykonalna, a wyjaśnienie nie zginie.

Zasada 3: dokumentacja jako kod (docs as code)

Dokumentacja trzymana w osobnym systemie niż kod szybko się rozjeżdża. Podejście docs as code oznacza, że:

1. Dokumentację piszesz w Markdownie (lub AsciiDoc, reStructuredText) w tym samym repozytorium co kod — więcej o samym repozytorium przeczytasz w tekście Git a GitHub.
2. Zmiana w kodzie i zmiana w dokumentacji trafiają do tego samego pull requestu i przechodzą to samo code review.
3. Stronę z dokumentacją generuje automatycznie potok CI, np. przy użyciu MkDocs, Docusaurus lub Sphinx.
4. Diagramy zapisujesz tekstowo (Mermaid, PlantUML), dzięki czemu da się je wersjonować i porównywać w diffie.
5. Linter (np. markdownlint, Vale) pilnuje formatowania i spójnej terminologii.

Wskazówka: Dopisz do definicji ukończenia zadania (Definition of Done) punkt „dokumentacja zaktualizowana lub potwierdzono, że nie wymaga zmian”. To najprostszy sposób, żeby dokumentacja nie zostawała w tyle.

Wiki (Confluence, Notion, Google Docs) nadal ma sens dla treści ogólnofirmowych — procesów, polityk, notatek ze spotkań. Opis działania konkretnego systemu powinien jednak mieszkać przy jego kodzie.

Zasada 4: konkret, spójność i przykłady

Dokumentacja techniczna jest czytana wybiórczo — ktoś trafia z wyszukiwarki na jedną sekcję i potrzebuje odpowiedzi natychmiast. Dlatego:

• jedno pojęcie, jedna nazwa — jeśli w jednym miejscu piszesz „klient”, a w innym „tenant” i „organizacja” na to samo, czytelnik założy, że to trzy różne rzeczy; prowadź krótki słownik pojęć,
• przykłady zamiast opisów — gotowe polecenie, przykładowy plik konfiguracyjny, zapytanie i odpowiedź API są warte więcej niż akapit tekstu,
• dokładne wersje i ścieżki — „PostgreSQL 16, plik /etc/app/config.yaml”, a nie „odpowiednia wersja bazy i plik konfiguracyjny”,
• krótkie akapity, nagłówki opisujące zadanie, listy numerowane dla kroków — skanowanie tekstu wzrokiem to norma, nie wyjątek,
• ostrzeżenia przed krokiem, nie po nim — informacja „to polecenie usuwa dane” musi być nad poleceniem.

Przy dokumentowaniu API korzystaj ze specyfikacji OpenAPI — z jednego pliku wygenerujesz interaktywną dokumentację, przykłady i klientów. Jeśli dopiero poznajesz ten temat, zacznij od naszego wprowadzenia do REST API.

Zasada 5: testuj i utrzymuj dokumentację

Dokumentacja, której nikt nie sprawdził, zwykle zawiera błędy. Kilka sposobów, by temu zapobiec:

1. Test nowej osoby — poproś kogoś spoza projektu, by przeszedł instrukcję krok po kroku bez Twojej pomocy. Każde pytanie, które zada, to brakujące zdanie w dokumencie.
2. Właściciel i data przeglądu — każdy dokument ma osobę odpowiedzialną i datę ostatniej weryfikacji w nagłówku.
3. Automatyczne testy przykładów — przykłady kodu można wykonywać w CI (np. doctest w Pythonie), a linki sprawdzać narzędziem do wykrywania martwych odnośników.
4. Usuwaj nieaktualne treści — przestarzała instrukcja jest gorsza niż jej brak, bo prowadzi w złą stronę. Archiwizuj ją z wyraźną adnotacją.

Narzędzia AI potrafią dziś wygenerować szkic README czy opis funkcji z kodu, ale nie znają kontekstu biznesowego ani historii decyzji. Traktuj je jak pomoc przy redakcji, nie jak autora — podobnie jak w przypadku vibe codingu, odpowiedzialność za treść zostaje po stronie zespołu.

Szablony dokumentacji technicznej do skopiowania

Poniższe szablony są punktem wyjścia — usuń sekcje, których nie potrzebujesz, zamiast zostawiać je puste.

Szablon README projektu

# Nazwa projektu

Jedno-dwa zdania: co robi ten system i dla kogo.

## Wymagania
- Node.js 22+ / Python 3.12+ / Docker 24+
- Dostęp do: VPN, bazy testowej, sekretów w menedżerze haseł

## Szybki start
1. Sklonuj repozytorium: `git clone ...`
2. Skopiuj konfigurację: `cp .env.example .env`
3. Uruchom: `docker compose up`
4. Otwórz http://localhost:8080

## Konfiguracja
| Zmienna | Opis | Domyślnie |
|---|---|---|
| DATABASE_URL | adres bazy danych | — |

## Testy
`make test`

## Wdrożenie
Link do instrukcji wdrożenia lub opis pipeline'u CI/CD.

## Architektura
Krótki opis + diagram + link do ADR.

## Kontakt
Zespół / kanał / właściciel projektu.

Szablon ADR (Architecture Decision Record)

ADR to krótki dokument zapisujący jedną decyzję architektoniczną. Numeruje się je kolejno i nigdy nie edytuje treści przyjętej decyzji — zmiana decyzji to nowy ADR, który „zastępuje” poprzedni.

# ADR-007: Wybór PostgreSQL jako głównej bazy danych

Status: Zaakceptowany (zastępuje ADR-002)
Data: 2026-09-10
Autorzy: imię i nazwisko

## Kontekst
Jaki problem rozwiązujemy, jakie mamy ograniczenia (wydajność, koszty, kompetencje zespołu).

## Rozważane opcje
1. PostgreSQL
2. MySQL
3. MongoDB

## Decyzja
Wybieramy PostgreSQL, ponieważ...

## Konsekwencje
Pozytywne: ...
Negatywne / ryzyka: ...

Szablon runbooka (procedury operacyjnej)

# Runbook: kolejka zamówień przestała przetwarzać wiadomości

Dotyczy: order-worker, środowisko produkcyjne
Właściciel: zespół Zamówienia | Ostatni przegląd: 2026-09-01

## Objawy
- alert "QueueDepthHigh" > 10 000 wiadomości
- klienci nie dostają potwierdzeń zamówień

## Diagnoza
1. Sprawdź stan podów: `kubectl get pods -n orders`
2. Sprawdź logi: `kubectl logs -n orders deploy/order-worker --tail=200`

## Naprawa
1. Jeśli pody są w CrashLoopBackOff — ...
2. Jeśli baza odrzuca połączenia — ...

## Eskalacja
Po 30 minutach bez poprawy: dyżurny zespołu Platforma, telefon z grafiku dyżurów.

Szablon wpisu w changelogu

Format Keep a Changelog grupuje zmiany według typu i wersji. Dobrze współgra z rozróżnieniem deployu i release’u — changelog opisuje to, co trafia do użytkowników w danym wydaniu.

## [2.4.0] - 2026-09-20
### Added
- Eksport raportów do CSV.
### Changed
- Domyślny limit stronicowania API zmieniony z 50 na 100.
### Fixed
- Błędne zaokrąglanie kwot w walucie EUR.
### Security
- Aktualizacja biblioteki JWT do wersji z poprawką bezpieczeństwa.

Szablon opisu endpointu API

## POST /api/v1/orders

Tworzy nowe zamówienie.

Uwierzytelnianie: Bearer token, zakres `orders:write`

Treść zapytania:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
| customerId | integer | tak | id klienta |
| items | array | tak | lista pozycji |

Odpowiedzi:
- 201 Created — zwraca obiekt zamówienia i nagłówek Location
- 400 Bad Request — błędne dane wejściowe
- 409 Conflict — zamówienie o tym numerze już istnieje

Przykład:
curl -X POST https://api.example.com/api/v1/orders -H "Authorization: Bearer ..." -d '{...}'

Tam, gdzie sam tekst nie wystarcza, dobrze sprawdzają się krótkie nagrania ekranu dołączone do instrukcji. Więcej o tym podejściu przeczytasz w artykule Loom i komunikacja asynchroniczna.

Od czego zacząć, jeśli projekt nie ma żadnej dokumentacji

Nie próbuj opisać wszystkiego naraz. Kolejność, która daje najwięcej korzyści przy najmniejszym wysiłku:

1. README z sekcją „Szybki start” — tak, żeby nowa osoba uruchomiła projekt lokalnie.
2. Runbooki dla najczęstszych awarii — zacznij od tych, które zdarzyły się w ostatnich miesiącach.
3. Lista zmiennych konfiguracyjnych i sekretów (bez wartości samych sekretów).
4. Diagram architektury — nawet odręczny szkic przeniesiony do Mermaid jest lepszy niż nic.
5. ADR-y dla nowych decyzji — starych nie musisz odtwarzać, ale od dziś zapisuj każdą istotną.

Ważne: Nigdy nie umieszczaj w dokumentacji haseł, tokenów ani kluczy prywatnych, nawet w „wewnętrznym” repozytorium. Wskazuj, gdzie znajduje się sekret (np. ścieżka w menedżerze haseł), a nie jego wartość.

Po kilku tygodniach takiej pracy zobaczysz efekt w liczbie pytań na czacie zespołu — to najbardziej wiarygodna miara tego, czy dokumentacja techniczna spełnia swoją rolę.