Podręczniki operatorskie¶
Podręcznik operatorski jest dokumentacją referencyjną komponentu. Wyjaśnia, do czego komponent służy, jak działa i z czym się komunikuje. Zbiera również jego kontrakty danych, ustawienia, limity, możliwe odmowy oraz stan zapisywany na dysku.
Rozgraniczenie rodzin dokumentacji operacyjnej:
- Podręcznik — opis komponentu i jego kontraktów. Czym jest, jak go skonfigurować i jakie dane udostępnia.
- Instrukcja awaryjna (runbook) — procedura. Co zrobić, gdy wystąpi określona sytuacja.
- HOWTO — instrukcja przeprowadzenia konkretnego zadania.
- FAQ — odpowiedź na pytanie.
Podręcznik odsyła do instrukcji awaryjnej zamiast powtarzać jej procedurę.
Nazwy typów, pól konfiguracji, tras i kodów błędów pozostają w oryginalnej
postaci code. Tekst objaśniający używa zwykłego języka i wprowadza termin
techniczny przy jego pierwszym użyciu.
Struktura podręcznika¶
Nagłówek dokumentu zawiera nazwę komponentu. Akapit otwierający krótko wyjaśnia jego rolę i odsyła do FAQ oraz HOWTO. Dalsze sekcje mają stałą numerację i kolejność:
- Cel i funkcje
- Zasada działania
- Umiejscowienie w architekturze i kanały komunikacji (z uzasadnieniem każdego kanału)
- Kontrakty danych — schematy, cel użycia, kanał przepływu
- Limity i zachowanie po ich przekroczeniu
- Słowniki niepowodzeń i statusów (kod, znaczenie, ponawialność)
- Autorytet i jego cofnięcie
- Granice zaufania — co komponent weryfikuje sam, a co przyjmuje od wołającego
- Zależności i tryby zdegradowane
- Stan trwały i restart
- Konfiguracja — składanie warstw, źródła, wartości domyślne
- Obserwowalność — status, ślady, liczniki
- Koszt i zasoby
- Wersje kontraktów i kompatybilność
- Znane ograniczenia
- Powiązanie z implementacją
Sekcja 16 jest obowiązkowa. Wskazuje odpowiadający komponentowi wpis w rejestrze implementacji, skrzynie Rust, schematy, zdolności i trasy. Dzięki temu można wykryć rozbieżność między podręcznikiem a kodem. Zasadę opisuje TRACEABILITY.md.