# Dokumentacja operacyjna systemu w Confluence

Dołącz ten plik do rozmowy w projekcie. Wskaż stronę nadrzędną Confluence, istniejące materiały i repozytorium. Agent porównuje je z poniższą strukturą, ustala z zespołem zakres i przygotowuje treść. Gdy nie ma dostępu do zapisu, przygotowuje materiał do wklejenia i jawnie oznacza, że strony nie zostały zapisane.

To dokumentacja działania i utrzymania systemu. Zasady pracy zespołu pozostają w playbooku, a status zadań w przyjętym planie lub Jira. Łącz je linkami; nie utrzymuj kilku niezależnych kopii tej samej reguły.

## Ustal ramy przed rozpoczęciem prac

Szkielet dokumentacji przygotuj przed pierwszym zadaniem. Szczególnie przy zewnętrznym zespole to ty ustalasz oczekiwania i pilnujesz przejrzystości projektu. Wykonawca uzupełnia uzgodnione opisy swojej pracy, a po twojej stronie musi być ktoś, kto sprawdza je przy odbiorze zmian. Nie odkładaj tego do końca współpracy.

- Firmowe miejsce dostępne przez cały projekt i po zakończeniu współpracy: **[link i administrator po naszej stronie]**
- Uzgodniony zakres dokumentacji: **[obszary ze struktury 00–11 poniżej]**
- Powiązanie z exit planem w umowie, czyli planem zakończenia współpracy: **[zakres przekazania dokumentacji i jej historii, termin, odbierający i sposób sprawdzenia]**
- Kto uzupełnia po stronie wykonawcy, kto sprawdza po naszej stronie: **[odpowiedzialności]**
- Kiedy sprawdzamy dokumentację razem z działającą zmianą: **[moment odbioru]**

Wpisz ustalenia do istniejącego playbooka lub planu. Dalsze strony wypełniaj wraz z decyzjami i realizacją; na początku nie wymyślaj odpowiedzi, których jeszcze nie ma.

## Punkt startu

- System / produkt i granice opisu:
- Projekt nowy czy istniejący:
- Strona główna dokumentacji w Confluence:
- Playbook, repozytoria i istniejący plan:
- Wersja systemu lub stan początkowy:
- Źródła, które agent może czytać:
- Uzgodniony zakres tworzenia lub aktualizacji stron:

## Struktura 00–11

Przy każdym obszarze zapisz: link, osobę uzupełniającą, osobę sprawdzającą, odpowiedzialnego za aktualność, wersję, datę sprawdzenia i otwarte braki.

| Obszar | Co trzeba opisać | Jak sprawdzić treść |
| --- | --- | --- |
| 00. Mapa dokumentacji i właściciele | Strony, zakresy, osoby i stan uzupełnienia | Druga osoba znajduje wiedzę i wie, do kogo zgłosić brak |
| 01. Architektura systemu | Cel, granice, części systemu, zależności i powody decyzji | Porównanie z kodem, konfiguracją oraz zapisanymi decyzjami |
| 02. Systemy, usługi i repozytoria | Za co odpowiada każdy element i gdzie jest kod | Odnośniki prowadzą do właściwych źródeł |
| 03. Model domenowy i dane | Pojęcia, reguły, wyjątki, znaczenie i przepływ danych | Osoba znająca dziedzinę potwierdza reguły i przykłady |
| 04. API i integracje | Wejścia, wyniki, błędy i uzgodnione kontrakty | Porównanie z implementacją i bezpieczną próbą lub testami |
| 05. Infrastruktura i środowiska | Gdzie system działa i gdzie jest konfiguracja | Porównanie opisu z potwierdzonym stanem |
| 06. Wdrożenia, wydania i wycofanie | Decyzje, wersje, sprawdzenie i cofnięcie | Dowód dla wskazanej wersji; uwzględnienie danych |
| 07. Monitoring i utrzymanie | Alerty, logi, odbiorcy i reakcja | Bezpieczna próba oraz potwierdzenie odbiorcy |
| 08. Kopie i odtworzenie po awarii | Co kopiujemy i jak odzyskujemy dane | Wynik próby odtworzenia, data i zakres |
| 09. Testy i jakość | Uruchamianie sprawdzeń, wyniki i znane luki | Wersja, faktyczne wyniki i niewykonane próby |
| 10. Bezpieczeństwo i dostępy | Role, nadawanie i odbieranie dostępu | Potwierdzenie przez odpowiedzialną osobę; bez poszerzania dostępu |
| 11. Instrukcje operacyjne | Kroki dla problemów, awarii i utrzymania | Druga osoba przechodzi instrukcję w bezpiecznym środowisku |

Nie umieszczaj haseł, tokenów, kluczy ani danych klientów. W razie potrzeby wskaż zatwierdzone miejsce przechowywania sekretów, bez ich wartości.

## Jak uzupełniamy dokumentację

### Nowy projekt

1. Przed rozpoczęciem prac załóż stronę główną i potrzebne podstrony w uzgodnionym miejscu. Wpisz znany cel, zakres, odpowiedzialności oraz źródła.
2. Po podjęciu decyzji dopisz ją z powodem do właściwej strony. Rozwiązanie niewdrożone oznacz jako planowane.
3. Po wykonaniu fragmentu dodaj opis działania, wersję i wyniki sprawdzeń.
4. Przy odbiorze etapu zweryfikuj powiązane strony. Przed oddaniem wersji uzupełnij wiedzę potrzebną do jej użycia i utrzymania.

### Istniejący system

1. Zrób mapę obecnych stron i luk. Rozróżnij brak treści, treść nieaktualną, sprzeczność i wiedzę potwierdzoną.
2. Uzupełnij najpierw obszary potrzebne do zmiany oraz krytyczne dla utrzymania. Korzystaj z kodu, konfiguracji, testów, bezpiecznych obserwacji i potwierdzeń ekspertów.
3. Pozostałe braki zapisz w istniejącym planie: co uzupełnić, kto odpowiada, kto sprawdzi i kiedy wracamy do tematu.
4. Przy modernizacji rozdziel stan obecny i docelowy. Po zmianie sprawdź dokumentację dla nowej wersji.

## Zawartość pojedynczej strony

- Obszar, produkt i wersja, których dotyczy:
- Osoba uzupełniająca / sprawdzająca / dbająca o aktualność:
- Stan: do uzupełnienia / do sprawdzenia / potwierdzone dla wersji:
- Data i źródło potwierdzenia:
- Co działa dzisiaj i dlaczego:
- Co dopiero planujemy:
- Instrukcja lub przykład potrzebny osobie korzystającej:
- Sprawdzenie, rzeczywisty wynik i dowód:
- Braki, sprzeczności i następny krok z istniejącego planu:
- Kiedy strona wymaga aktualizacji:

„Potwierdzone” wymaga dowodu i weryfikacji odpowiedzialnej osoby. Jeżeli obszar nie dotyczy projektu, wpisz „nie dotyczy” oraz konkretny powód.

## Wypełnijcie pierwszą stronę z własnej pracy

Weźcie funkcję, którą właśnie planujecie albo zmieniacie. Otwórzcie jej zadanie, dokumentację i kod. Agent przygotowuje treść do właściwej strony Confluence z tych źródeł.

| Moment | Co zapisujemy |
| --- | --- |
| Przed wykonaniem | Potrzeba użytkownika, uzgodnione działanie, wyjątki i powody decyzji; oznaczone jako plan, jeśli jeszcze nie działają |
| Po pokazaniu zmiany | Jak użytkownik korzysta z funkcji, wynik demo i otwarte uwagi |
| Po sprawdzeniu | Wersja, wykonane próby, wyniki i osoba sprawdzająca |
| Po wydaniu | Potwierdzony stan na docelowym środowisku oraz potrzebna instrukcja obsługi lub utrzymania |

### Gdy stary opis nie zgadza się z aplikacją

Zapiszcie obok siebie konkretny fragment dokumentu i wynik próby na obecnej wersji. Dołączcie źródła. Zapytajcie osobę znającą regułę, który wynik jest właściwy i dlaczego. Do odpowiedzi oznaczcie różnicę jako nierozstrzygniętą.

Po odpowiedzi dopiszcie decyzję, uzasadnienie, osobę i datę. Jeśli kod wymaga zmiany, powiążcie decyzję z zadaniem. Nie zmieniajcie opisu stanu obecnego na docelowy, dopóki aplikacja nadal działa po staremu. Dopiero po zmianie i sprawdzeniu zapiszcie nowy stan.

**Sprawdzenie:** dajcie stronę osobie, która nie uczestniczyła w rozmowie. Niech wyjaśni działanie funkcji, wskaże wyjątek i powie, co jeszcze nie jest rozstrzygnięte. Braki uzupełnijcie w tej samej stronie.

## Prompt do uzupełnienia dokumentacji

```text
Przeczytaj ten szablon oraz dozwolone źródła: [linki]. Najpierw utwórz mapę
istniejących stron i luk. Dla każdego uzupełnionego fragmentu podaj źródło,
wersję, datę oraz osobę sprawdzającą. Oddziel stan obecny od planu.
Przy sprzeczności zapisz oba źródła i pytanie do właściciela, bez zgadywania.
Przygotuj treść do wspólnego uzgodnienia i wskaż właściwą stronę Confluence.
Nie zapisuj stron, nie zmieniaj dostępu, kont, środowisk ani zewnętrznych usług.
```