Dokumentacja IT, której nikt nie czyta — i ta, która ratuje dzień

Prawie każda firma, która kiedykolwiek miała audyt albo zmieniała dostawcę IT, ma jakąś dokumentację. Prawie żadna z nich nie jest używana.

Powód jest zawsze ten sam: dokument powstał, żeby istnieć, a nie żeby ktoś z niego korzystał. Ma sto stron, jest kompletny w dniu powstania i nieaktualny po trzech miesiącach, bo aktualizowanie go byłoby osobną pracą.

Ta notatka jest o tym, co warto prowadzić, żeby faktycznie się przydawało.

Test przydatności

Jedno pytanie rozstrzyga, czy dokument ma sens:

Czy ktoś, kto nie zna tego środowiska, jest w stanie na jego podstawie rozwiązać awarię o drugiej w nocy?

Jeżeli odpowiedź brzmi „nie, ale wie, jaka jest polityka bezpieczeństwa” — to jest dokument do audytu, nie do pracy. Oba mają rację bytu, tylko nie należy ich mylić.

Cztery dokumenty warte prowadzenia

1. Mapa: co gdzie stoi i od czego zależy

Nie schemat sieci z ikonkami, tylko odpowiedź na pytanie „co przestanie działać, jeżeli wyłączę to”.

Minimalna wersja to lista z czterema kolumnami: co to jest, gdzie fizycznie stoi albo u jakiego dostawcy, do czego jest potrzebne, co się zepsuje bez tego.

Wartość widać dopiero przy awarii, ale wtedy jest ogromna: skraca fazę zgadywania, która przy nieznanym środowisku bywa dłuższa niż sama naprawa.

2. Dostępy: gdzie są i kto je ma

Nie hasła — te należą do menedżera haseł. Chodzi o listę miejsc, do których w ogóle trzeba mieć dostęp: panel domeny, panel hostingu, konsole usług chmurowych, dostawcy, konta administracyjne urządzeń.

To ten dokument, którego brak boli najbardziej, gdy odchodzi osoba prowadząca IT. Odzyskanie dostępu do domeny zarejestrowanej na czyjś prywatny adres potrafi trwać tygodniami.

3. Dziennik decyzji

Najrzadziej prowadzony i najbardziej niedoceniany. Kilka linijek przy każdej istotnej zmianie: co zmieniono, kiedy i dlaczego.

„Dlaczego” jest tu jedyną częścią, której nie da się odtworzyć później z samego środowiska. Za dwa lata każdy zobaczy, że jest wyjątek w zaporze — nikt nie będzie wiedział, czy nadal jest potrzebny. Bez tej wiedzy wyjątków się nie usuwa, tylko dokłada.

Ten dokument kosztuje minutę przy każdej zmianie i oszczędza godziny przy każdym przeglądzie.

4. Krótkie instrukcje dla użytkowników

Jedna strona na temat: jak podłączyć się do zasobu sieciowego, jak zgłosić problem, co zrobić po zgubieniu telefonu z uwierzytelnianiem.

Wartość jest wymierna: to są rzeczy, o które ludzie pytają najczęściej, a odpowiedź jest za każdym razem taka sama.

Zasady, które sprawiają, że to żyje

Trzymaj to blisko rzeczy, których dotyczy. Dokumentacja w osobnym systemie, do którego trzeba się osobno logować, nie jest aktualizowana. Pliki tekstowe w repozytorium albo strony w narzędziu, którego zespół i tak używa, mają znacznie większe szanse.

Aktualizuj przy zmianie, nie przy przeglądzie. Zapis powstający w momencie wprowadzania zmiany kosztuje minutę. Odtwarzanie tego samego pół roku później kosztuje godzinę i wychodzi gorzej.

Pisz dla kogoś, kto tego nie zna. Skrót zrozumiały dla autora jest bezużyteczny dla następcy — a dokumentacja jest właśnie po to, żeby następca nie zaczynał od zera.

Zapisuj rzeczy dziwne. Wyjątek, obejście, maszyna, której nie wolno zaktualizować, urządzenie z niestandardowym ustawieniem. To jest najcenniejsza część dokumentacji, bo jedyna, której nie da się wywnioskować.

Rzecz, którą warto powiedzieć wprost

Dokumentacja środowiska należy do firmy, nie do osoby, która je obsługuje. Jeżeli po zakończeniu współpracy zostaje pusty katalog i wiedza w cudzej głowie, to nie była usługa — to była zależność.

Dlatego przy stałej opiece traktuję ją jako część zakresu, a nie jako dodatek. Sprawdzianem jest zawsze to samo pytanie: czy ktoś inny poradzi sobie z tym środowiskiem bez dzwonienia do mnie.