Dokumentacja systemu w Confluence

Playbook wyjaśnia, jak pracuje zespół. Dokumentacja operacyjna opisuje, jak działa system, jak go rozwijać i co zrobić, gdy pojawi się problem. Potrzebujecie obu. Sama lista pustych stron w Confluence jeszcze nie pomaga w pracy.

Moja lekcja: dokumentacja zaczyna się przed pierwszym zadaniem

Tę lekcję wyniosłem z realizacji projektu z zewnętrznym software house’em. Dokumentacja istniała, ale jej struktura powstawała doraźnie.

Szkielet dokumentacji przygotuj na samym początku projektu. Szczególnie gdy zaczynasz pracę z zewnętrznym zespołem. To ty odpowiadasz za przejrzystość projektu i za ustalenie ram współpracy. Nie zakładaj, że wykonawca sam domyśli się, jakiej dokumentacji potrzebujesz.

Moja lekcja jest prosta: jeśli nie dasz ram na początku, na końcu dostaniesz słabą dokumentację. Ustal z zespołem jeszcze przed pierwszym zadaniem:

• Gdzie zapisujecie wiedzę — firmowe konto i przestrzeń, z administratorem po twojej stronie oraz dostępem przez cały projekt i po zakończeniu współpracy.
• Co ma być opisane — szkielet stron, który wypełniacie wraz z decyzjami i realizacją.
• Kto uzupełnia, a kto sprawdza — po stronie wykonawcy i po twojej stronie.
• Kiedy sprawdzacie aktualność — przy odbiorze kolejnych zmian, a nie dopiero przy zakończeniu współpracy.

Zewnętrzny zespół odpowiada za uzgodnione opisy swojej pracy. Ty ustalasz oczekiwania i pilnujesz, żeby dokumentacja rzeczywiście powstawała. Na początku nie musicie znać wszystkich odpowiedzi. Musicie wiedzieć, gdzie je zapiszecie i kto za nie odpowiada. Pozostałe lekcje ze współpracy z wykonawcą pokazują, dlaczego narzędzia, domeny i chmura mają być firmowe od początku oraz co ustalić w exit planie, czyli planie zakończenia współpracy.

Przygotujcie strukturę i osoby odpowiedzialne

W swojej dokumentacji użyłem poniższego układu. Możecie go wykorzystać w projekcie, dopasowując zakres do systemu. Jeśli macie już dokumentację, przyporządkujcie istniejące strony do tych obszarów.

• 00. Mapa dokumentacji i właściciele — gdzie jest wiedza, kto ją uzupełnia, kto sprawdza i kiedy ostatnio porównał ją z systemem.
• 01. Architektura systemu — z czego składa się system, jak części ze sobą współpracują i dlaczego wybrano takie rozwiązanie.
• 02. Systemy, usługi i repozytoria — gdzie jest kod poszczególnych elementów i za co one odpowiadają.
• 03. Model domenowy i dane — pojęcia używane w produkcie, reguły, wyjątki i znaczenie przechowywanych danych.
• 04. API i integracje — jak systemy wymieniają dane, czego od siebie oczekują i co dzieje się przy błędzie.
• 05. Infrastruktura i środowiska — gdzie aplikacja działa, do czego służy każde środowisko i gdzie jest jego konfiguracja.
• 06. Wdrożenia, wydania i wycofanie wersji — jak uruchomić zmianę, sprawdzić ją i wrócić do poprzedniego stanu.
• 07. Monitoring i utrzymanie — jak zauważacie problem, gdzie szukacie jego przyczyny i kto reaguje.
• 08. Kopie zapasowe i odtworzenie po awarii — co jest kopiowane, jak odzyskać dane i kiedy sprawdzono, że to działa.
• 09. Testy i jakość — co i jak sprawdzacie, gdzie są wyniki i czego jeszcze nie sprawdzono.
• 10. Bezpieczeństwo i dostępy — kto powinien mieć dostęp, jak go uzyskać i odebrać oraz gdzie są zasady ochrony danych. Bez haseł i tokenów.
• 11. Instrukcje operacyjne — konkretne kroki, np. co zrobić po alercie, awarii integracji albo nieudanym wdrożeniu. Takie instrukcje nazywa się też runbookami.

Każda strona ma osobę dbającą o aktualność i kogoś, kto potwierdza treść. Dodajcie datę, wersję systemu oraz źródła. Używajcie prostych oznaczeń: do uzupełnienia, do sprawdzenia, potwierdzone dla wersji. Jeśli obszar nie dotyczy projektu, zapiszcie dlaczego. Planowane rozwiązanie odróżniajcie od tego, co już działa.

Nowy projekt: uzupełniajcie wraz z pracą

Przed rozpoczęciem prac załóżcie w Confluence stronę główną i potrzebne podstrony. Od razu wpiszcie to, co już ustaliliście: cel, zakres systemu, osoby odpowiedzialne i odnośniki do repozytorium oraz planu. Resztę uzupełniajcie wtedy, gdy podejmujecie decyzje i budujecie kolejne części.

Po wyborze rozwiązania agent dopisuje architekturę i uzasadnienie. Po dodaniu integracji — sposób wymiany danych. Po przygotowaniu wdrożenia — instrukcję uruchomienia i cofnięcia. Przy odbiorze etapu sprawdzacie również związane z nim strony. Dokumentacja potrzebna do bezpiecznego użycia i utrzymania danej wersji musi być uzupełniona przed jej oddaniem.

Istniejący system: znajdźcie luki i je uzupełnijcie

Najpierw porównajcie tę mapę z obecną dokumentacją. Zaznaczcie, co istnieje, czego brakuje, co jest sprzeczne i co wymaga sprawdzenia. Materiały od poprzedniego zespołu lub wykonawcy są źródłem do weryfikacji — mogą opisywać dawną wersję systemu.

Uzupełniajcie wiedzę na podstawie kodu, konfiguracji, testów, bezpiecznych prób i rozmów z osobami znającymi dziedzinę. Zacznijcie od obszarów potrzebnych do najbliższej zmiany oraz krytycznych dla utrzymania. Pozostałe braki dostają osobę odpowiedzialną i miejsce w istniejącym planie. Nie kończcie na wypisaniu luk.

Przy modernizacji rozdzielcie opis tego, co działa dzisiaj, od rozwiązania docelowego. Po przełączeniu fragmentu systemu zaktualizujcie dokumentację stanu faktycznego. Historycznego powodu decyzji nie zgadujcie wyłącznie z kodu.

Gdy dokument, kod i ekspert mówią co innego

Jeśli instrukcja opisuje inne działanie niż aplikacja, zapiszcie rozbieżność przy zmienianej funkcji. Agent powinien pokazać oba źródła i odtworzyć przypadek w bezpiecznym podglądzie. Sam kod nie wyjaśni, czy to błąd, czy dawna decyzja, której nikt nie dopisał do dokumentacji.

Do wyjaśnienia oznaczcie ten fragment jako nierozstrzygnięty. Po odpowiedzi właściciela reguły dopiszcie decyzję i potrzebny test. Przy odbiorze otwórzcie stronę obok demo: czy opisuje pokazaną wersję? W pobieranym pliku jest wzór zapisu rozbieżności i dalszego postępowania.

Dajcie agentowi strukturę do wypełnienia

Pobierzcie plik, dołączcie go do rozmowy w projekcie i wskażcie miejsce w Confluence. Jeśli agent ma właściwy dostęp, po uzgodnieniu zakresu może tworzyć lub aktualizować strony. Jeśli nie, przygotuje treść do wklejenia i poda, gdzie powinna trafić. Samo przygotowanie tekstu nie oznacza zapisania go w Confluence.

Przygotuj z nami dokumentację operacyjną systemu [nazwa] w Confluence [strona nadrzędna]. Projekt jest [nowy / istniejący]. Przeczytaj załączony plik, playbook i dostępne źródła [linki]. Najpierw sprawdź dostęp i porównaj proponowaną strukturę z obecnymi stronami. Pokaż, które strony wykorzystasz, co trzeba uzupełnić i czego nie da się jeszcze potwierdzić. Nie twórz duplikatów. Dla każdego obszaru ustal z nami osobę uzupełniającą, sprawdzającą i odpowiedzialną za aktualność. Po uzgodnieniu zakresu wypełniaj strony potwierdzoną wiedzą. Podawaj źródło, wersję i datę; oddziel plan od stanu działającego systemu. Przy brakach pytaj, zamiast wymyślać treść. Pozostałe uzupełnienia wpisz do istniejącego planu i wracaj do nich podczas realizacji. Przed odbiorem etapu sprawdź strony dotyczące tej zmiany. Nie oznaczaj treści jako potwierdzonej tylko dlatego, że ją wygenerowałeś. Jeśli nie możesz zapisać stron w Confluence, przygotuj treść do wklejenia i powiedz, co nadal wymaga zapisania. Nie umieszczaj sekretów.

Sprawdźcie dokumentację w użyciu

Druga osoba powinna znaleźć repozytorium, zrozumieć ważną regułę i przejść potrzebną instrukcję na bezpiecznym środowisku. Przy opisie kopii zapasowej potrzebny jest wynik próby odtworzenia; przy wdrożeniu — wynik sprawdzenia wersji. Sam tekst nie jest dowodem wykonania tych prób.

Wynik: Confluence zawiera uzupełnioną, sprawdzoną wiedzę potrzebną na danym etapie. Otwarte braki są widoczne i mają właściciela oraz następny krok. Dokumentacja zmienia się razem z systemem.