Dokumentacja techniczna powstaje najrzadziej i jest potrzebna w najgorszych momentach — przy awarii i przy zmianie osoby odpowiedzialnej.
Co warto opisać
- konfiguracje i miejsca ich przechowywania,
- sposób odtworzenia środowiska,
- rozwiązania powtarzających się awarii,
- decyzje projektowe wraz z uzasadnieniem,
- zależności między systemami,
- dane kontaktowe do dostawców.
Zależności między systemami są w małych firmach najczęściej pomijane i najdroższe w skutkach. Kiedy zmiana w jednym miejscu psuje coś w drugim, a nikt nie pamięta, że te systemy w ogóle się ze sobą komunikują, szukanie przyczyny zajmuje więcej czasu niż sama naprawa.
Dlaczego, nie tylko jak
Zapis powodu decyzji jest cenniejszy niż opis konfiguracji. Konfigurację da się odczytać z systemu, powodu — nie.
Bez powodu następna osoba stoi przed wyborem: zostawić dziwne ustawienie i nie wiedzieć czemu, albo je zmienić i wywołać awarię, którą ktoś kiedyś już naprawiał. Jedno zdanie zapisane przy zmianie zamyka ten problem na lata.
Opis awarii po jej usunięciu
Objawy, przyczyna, rozwiązanie. Piętnaście minut zapisu oszczędza godzin przy następnym wystąpieniu, zwykle za pół roku.
Najważniejsza jest część o objawach, bo według niej będzie się szukać. Opis „system zwracał błąd przy zapisie dokumentu po godzinie zamknięcia zmiany" znajdzie się w wyszukiwaniu; opis „problem z zapisem" nie znajdzie się nigdy. Zasady formułowania takich tytułów zbiera tekst o procedurach i instrukcjach stanowiskowych.
Przy dokumentacji, nie obok
Opis trzymany blisko konfiguracji jest aktualizowany. Dokument w osobnym miejscu rozjeżdża się z rzeczywistością.
Dla firmy oznacza to jedną decyzję: gdzie mieszka opis techniczny i czy baza wiedzy ma go kopiować, czy tylko indeksować w miejscu, w którym leży. Druga opcja jest niemal zawsze lepsza, bo eliminuje drugie źródło prawdy.
Test przejęcia
Czy inna osoba jest w stanie na podstawie opisu przejąć system. Jeśli nie — dokumentacja jest niepełna, choćby wyglądała obszernie.
Test da się przeprowadzić bez czekania na odejście kogokolwiek. Wystarczy poprosić drugą osobę, żeby według opisu wykonała konkretną czynność, a autor siedział obok i notował pytania. Każde pytanie to brak w dokumentacji. Jedno popołudnie daje listę uzupełnień lepszą niż tygodnie pisania na zapas.
Dane dostępowe
Nie w bazie wiedzy. Odsyłacz do miejsca, w którym są przechowywane bezpiecznie, w zupełności wystarcza.
Ta zasada dotyczy też zrzutów ekranu i fragmentów konfiguracji wklejanych do opisu. Łatwo przeoczyć w nich adres serwera albo nazwę konta. Warto to sprawdzać przy zakładaniu wpisu, a nie przy przeglądzie po roku.
Kto to utrzymuje
Dokumentacja techniczna w małej firmie zwykle nie ma właściciela, bo obsługę prowadzi zewnętrzny dostawca. To da się rozwiązać dwoma ustaleniami: dostawca oddaje opis w formie, którą firma może czytać i przeszukiwać, a jedna osoba po stronie firmy sprawdza raz w roku, czy opis nadal pasuje do rzeczywistości. Więcej o tej roli mówi tekst o właścicielu treści w bazie wiedzy, a o rytmie przeglądów — tekst o aktualności treści.
