Mówi się o CI/CD (Continuous Integration i Continuos Development) a o dokumentacji to już nikt nie pamięta…
Ciągła integracja i ciągłe wdrażanie (CI/CD) to koncepcje dobrze znane programistom i administratorom. Zespoły deweloperów i devopsi uparcie pracują nad tym aby „coś’ wykonało za nich większość powtarzalnej pracy, zmniejszając obciążenie codziennymi obowiązkami. Potoki w ramach CI/CD to swego rodzaju drugi mózg, który za nas pamięta, aby wykonać każdą drobną kontrolę, test lub zadanie dokładnie we właściwym momencie, automatycznie integrując, testując, wdrażając nasze oprogramowanie za nas. Ale zaraz, co z dokumentacją? Dlaczego zamiatamy ten temat niejako pod dywan?
Czym właściwie jest ciągła dokumentacja?
Po pierwsze, pod mianem Continuous Documentation kryje się wzorzec behawioralny i organizacyjny, który zasypuje dziurę między zmianami w bazie kodu a jego dokumentacją za pomocą automatyzacji (documentation-as-code) oraz ustandaryzowanych przepływów pracy i potoków. Mówiąc bardziej wprost: jest to praktyka aktualizowania dokumentacji równolegle do aktualizacji kodu.
Dokumentacja i inne dokumenty (do dokumentacji sensu stricte nie wliczymy różnego rozdaju dokumentów towarzyszących jak dokumenty wprowadzające, projektowe, przeglądy architektury) bardzo często nie idą w parze ze zmianami w kodzie źródłowym. Są przechowywane w zupełnie innych repozytoriach i narzędziach (takich jak Confluence, Wiki, Sharepoint czy Teams). Nic dziwnego, że zawsze są nieaktualne, niekompletne i po prostu nieprawidłowe, zwłaszcza jeżeli ktoś kto taką dokumentację sporządza nie czyta TeamQuesta.
Dlaczego dokumentacja niepowiązana z kodem jest zła?
Przez nie łączenie dokumentacji z bazą kodu tworzymy sobie przyszłą pracę, zawsze odkładaną na potem. Powstają nam: dług dokumentacyjny, martwe punkty w zakresie dokumentacji a wreszcie zostajemy z przestarzałą i niekompletną dokumentacją.
Na braku aktualnej dokumentacji cierpi też niemal każdy proces biznesowy związany z tworzeniem oprogramowania. Procesy te obejmują wprowadzanie nowych programistów do zespołu lub też przeniesienia programisty z jednego projektu czy zespołu do innego. Stara dokumentacja wywiera też wpływ na użytkowników końcowych i klientów, w zakresie w jakim dokumentacja ta jest do nich akurat skierowana.
Wreszcie brak oficjalnego, aktualnego źródła wiedzy „pisanej” ma również inne negatywne skutki: bierze udział w tworzeniu wiedz „plemiennej”, opartej na ustnym przekazie pomiędzy członkami zespołu. Nie można pisać oprogramowania czerpiąc wiedzę o tym jak ono działa wyłącznie przy ekspresie do kawy albo w drodze na papierosa. To ostatecznie prowadzi do niezdrowej kultury technicznej (w zasadzie jej braku). A co jeśli jeden programista z drugim dojdzie do wniosku, że przekazywanie wiedzy nie leży w jego najlepszym interesie?
Do CD potrzebujemy narzędzi
Dokumentacja ciągła, podobnie jak wszystkie inne paradygmaty ciągłego doskonalenia (devopsi wiedzą o czym piszemy), polega na narzędziach. Nie da się aktualizować dokumentacji zsynchronizowanej z pracą na rzeczywistej bazie kodu bez zautomatyzowania a więc bez odpowiednich programów.
Istnieje wiele przykładów narzędzi do ciągłej dokumentacji, które mogą pomóc. Na przykład Swimm.io to narzędzie do takich zadań i IDE w jednym, które w miarę możliwości automatycznie synchronizuje dokumentację. Jego algorytm identyfikuje i automatycznie koryguje dokumentację „podłączoną” do kodu, zmniejszając lukę między bazą kodu a dokumentacją, gdy zmienia się kod źródłowy. Swimm buduje i aktualizuje dokumentację stopniowo, utrzymując ją w synchronizacji z bazą kodu, automatycznie koryguje niespójności i nieścisłości i pokazuje stopień pokrycia dokumentacji dla danego wycinku kodu. Zupełnie tak jak znamy to z pokrycia testami.
