Jak utrzymać dokumentację automatyzacji zgodną z rzeczywistością?

Dokumentacja automatyzacji często jest poprawna tylko w dniu odbioru. Później zmienia się formularz, integracja, warunek biznesowy albo osoba zatwierdzająca, a opis pozostaje bez zmian. Po kilku miesiącach zespół ma dwa procesy: ten, który naprawdę działa, i ten zapisany w dokumencie.

Problem nie polega więc wyłącznie na tym, jak dobrze opisać proces przed wdrożeniem. Trzeba również zaprojektować sposób, w jaki dokumentacja będzie aktualizowana razem z automatyzacją, porównywana z poprzednią wersją i sprawdzana na prawdziwych przypadkach.

Ustal, co jest źródłem prawdy o działającym procesie

Opis napisany z pamięci szybko się rozchodzi z rzeczywistością. Najpierw wskaż elementy, z których można odtworzyć faktyczny przebieg automatyzacji:

• wersję konfiguracji lub kodu;
• schemat kroków i połączeń;
• listę systemów, formularzy i integracji;
• reguły decyzyjne oraz progi;
• dane wejściowe i rezultaty poszczególnych kroków;
• uprawnienia używane przez automat;
• historię wdrożeń i zmian;
• logi pokazujące najczęstsze ścieżki oraz błędy.

Nie oznacza to, że dokumentacja ma być kopią kodu. Kod może dokładnie pokazać, co robi system, ale nie wyjaśniać, po co istnieje dany krok, kto odpowiada za decyzję i jaki skutek biznesowy ma błąd. Potrzebne są oba poziomy: techniczny ślad wykonania oraz zrozumiały opis celu i odpowiedzialności.

Rozdziel opis generowany od treści zatwierdzonej

AI może pomóc przygotować dokumentację na podstawie uporządkowanego schematu procesu. Nie powinno jednak samodzielnie ogłaszać wygenerowanego opisu jako obowiązującej procedury.

Opis generowany automatycznie jest propozycją. Człowiek nadal powinien sprawdzić:

• czy nazwy kroków odpowiadają językowi używanemu w firmie;
• czy model poprawnie wyjaśnił warunki i wyjątki;
• czy nie dopisał celu, którego nie ma w danych wejściowych;
• czy wskazał właściwy system źródłowy;
• czy nie ujawnił danych technicznych lub poufnych szerszej grupie odbiorców;
• czy opis pozwala odtworzyć odpowiedzialność za decyzję.

Oficjalne studium Boomi Scribe opisuje podejście, w którym przepływ integracyjny jest najpierw przekształcany do uporządkowanego grafu. Dopiero taki materiał trafia do modelu generującego dokumentację. System porównuje także wersje komponentów i pokazuje dodane, zmienione oraz usunięte elementy. To przykład architektury, a nie gwarancja, że każdy wygenerowany opis będzie poprawny.

Zapisuj minimalny komplet informacji

Dokumentacja nie musi być wielkim podręcznikiem. Powinna jednak pozwolić nowej osobie zrozumieć, co uruchamia proces, co dzieje się po drodze i kiedy potrzebna jest reakcja człowieka.

Dla każdej automatyzacji warto zapisać co najmniej:

1. cel biznesowy i miernik rezultatu;
2. początek oraz warunek zakończenia;
3. główne kroki i kolejność ich wykonania;
4. systemy i źródła danych;
5. decyzje, progi i wyjątki;
6. właściciela procesu oraz właściciela technicznego;
7. wymagane uprawnienia;
8. sposób monitorowania i alarmowania;
9. procedurę ręczną na wypadek awarii;
10. numer wersji, datę przeglądu i osobę zatwierdzającą.

Taki zestaw łączy perspektywę procesu z informacjami potrzebnymi do utrzymania rozwiązania. Jest też zgodny z podejściem procesowym ISO: proces powinien mieć określony cel, wejścia, wyjścia, odpowiedzialności, ryzyka, mierniki i sposób doskonalenia.

Traktuj zmianę dokumentacji jako część wdrożenia

Jeżeli aktualizacja opisu jest osobnym zadaniem „na później”, zwykle przegrywa z pilniejszą pracą. Lepszym zabezpieczeniem jest dodanie jej do definicji ukończenia zmiany.

Przed wdrożeniem sprawdź:

• co zmieniło się względem poprzedniej wersji;
• które fragmenty dokumentacji tracą ważność;
• czy zmieniły się dane, integracje albo uprawnienia;
• czy doszedł nowy wyjątek lub punkt kontroli;
• kto zatwierdzi opis po zmianie;
• czy instrukcja awaryjna nadal działa.

Zmiana nie powinna otrzymać statusu zakończonej, dopóki opis, schemat i lista odpowiedzialności nie odpowiadają wersji przeznaczonej na produkcję. W małej firmie może to być krótka lista kontrolna dołączona do zadania. Nie jest potrzebny rozbudowany system, jeśli prostszy mechanizm rzeczywiście blokuje zamknięcie nieudokumentowanej zmiany.

Porównuj wersje zamiast przepisywać cały dokument

Pełny dokument po aktualizacji może wyglądać poprawnie, a mimo to ukrywać istotną zmianę. Dlatego obok aktualnej wersji potrzebne jest porównanie pokazujące:

• kroki dodane i usunięte;
• zmienione warunki;
• nowe źródła danych;
• zmianę odbiorcy lub właściciela;
• rozszerzone uprawnienia;
• zmianę obsługi błędu;
• wpływ na procesy zależne.

Porównanie pomaga osobie zatwierdzającej skupić się na konsekwencjach. Jest szczególnie ważne, gdy drobna techniczna poprawka zmienia decyzję biznesową, zakres danych albo zachowanie systemu w sytuacji wyjątkowej.

Historia wersji nie powinna zastępować aktualnego opisu. Użytkownik potrzebuje jednego obowiązującego dokumentu, a historia służy do wyjaśnienia, kiedy i dlaczego zmieniły się zasady.

Sprawdzaj dokumentację na prawdziwym przypadku

Sam przegląd tekstu nie pokazuje, czy opis odpowiada produkcji. Raz na ustalony okres wybierz rzeczywiste zamówienie, zgłoszenie lub dokument i przejdź jego drogę od początku do końca.

Podczas kontroli odpowiedz na pytania:

• czy zdarzenie uruchomiło proces zgodnie z opisem;
• czy dane przyszły ze wskazanego miejsca;
• czy kroki wykonały się w zapisanej kolejności;
• czy warunek decyzji zadziałał tak, jak opisano;
• czy wyjątek został rozpoznany i obsłużony;
• czy alarm trafił do właściwej osoby;
• czy rezultat można powiązać z konkretną wersją procesu.

Jeżeli dokumentacja nie pozwala wyjaśnić prawdziwego przebiegu, wymaga poprawy. Jeżeli przebieg różni się od zatwierdzonej dokumentacji, trzeba ustalić, czy nieaktualny jest opis, czy sama automatyzacja działa poza uzgodnionymi zasadami.

Ustal częstotliwość przeglądu według ryzyka

Nie każda automatyzacja potrzebuje takiego samego nadzoru. Proces informacyjny używany kilka razy w miesiącu może być sprawdzany rzadziej niż mechanizm, który codziennie zmienia dane klientów, wystawia dokumenty lub uruchamia płatności.

Częstszy przegląd jest potrzebny, gdy:

• skutek błędu jest kosztowny albo trudny do odwrócenia;
• proces używa danych poufnych;
• zmiany w systemach źródłowych pojawiają się często;
• wiele innych procesów zależy od rezultatu;
• reguły biznesowe lub regulacyjne szybko się zmieniają;
• automat ma szerokie uprawnienia;
• rośnie liczba ręcznych interwencji i wyjątków.

Przegląd powinien mieć właściciela i termin. Samo pole „data aktualizacji” niczego nie zabezpiecza, jeżeli nikt nie odpowiada za decyzję, czy dokument nadal jest obowiązujący.

Zacznij od jednej automatyzacji

Nie trzeba od razu przebudowywać całego systemu dokumentacji. Wybierz proces ważny, często zmieniany albo szczególnie trudny do utrzymania.

Na początku:

1. wskaż techniczne źródła prawdy;
2. przygotuj minimalny obowiązujący opis;
3. połącz zmianę dokumentacji z wdrożeniem;
4. dodaj porównanie wersji;
5. sprawdź opis na prawdziwym przypadku;
6. ustal właściciela i następny termin przeglądu.

Automatyczne generowanie dokumentacji ma sens dopiero wtedy, gdy system dostaje uporządkowane, wersjonowane dane i istnieje jasna kontrola człowieka. Bez tego AI może tylko szybciej tworzyć eleganckie opisy procesu, który nigdy nie działał w przedstawiony sposób.

Najważniejszym rezultatem nie jest więc liczba stron dokumentacji. Jest nim możliwość szybkiego ustalenia co działa teraz, co zmieniło się od poprzedniej wersji, kto to zatwierdził i jak sprawdzić przebieg na faktach.