Jak tworzyć dokumentację? Doświadczenia Software Engineera    

Dokumentacja systemów informatycznych to bardzo szeroki temat. Rzadko spotyka się projekty z aktualną i wiarygodną bazą wiedzy, dlatego chciałbym podzielić się kilkoma przemyśleniami w temacie. Na co dzień pracuję z systemami Enterprise, jednak koncepty możecie wykorzystać w każdym systemie.

Pierwszym problemem jest nasz target, czyli grupa docelowa. Tak jak w dobrej dokumentacji, tak i ten artykuł będzie skupiał się na określonych odbiorcach. Opiszę dokumentację biznesową i techniczną dla użytkowników wewnętrznych. Instrukcje dla użytkowników docelowych to trochę inny temat.

Dlaczego dokumentujemy?

Odpowiedź jest prosta: tworzymy dokumentację ponieważ nieposiadanie bazy wiedzy jest drogie. Pomyślcie o godzinach spędzonych na spotkaniach ustalających szczegóły implementacji, handovery i on-boardingi. Dobra dokumentacja sprawi, że ten czas do Was wróci. Niestety bazy wiedzy mają tę specyfikę, że same stają się drogie, jeśli nie są odpowiednio zaplanowane.

Czym jest dokumentacja?

Dokumentacja to po prostu informacja o naszym systemie. Zastanówmy się, jakie cechy ma dobra baza wiedzy:

• Aktualna – jeśli znajdę nieaktualne informacje, przestaję ufać temu źródłu,
• Zrozumiała – napisana prostym językiem,
• Łatwa do znalezienia – możesz opisać wszystko w perfekcyjny sposób. Wszystko to jest nic nie warte, jeśli użytkownik do tej strony nie dojdzie,
• Łatwa w utrzymaniu – najlepiej bez wysiłku, niech się dzieje samo.

Dokumentacja biznesowa

Domain Driven Docs

Moją receptą jest kształtowanie wiedzy w oparciu o domenę (niezbyt odkrywcze, jednak zaskakująca rzadko stosowane). Idea jest prosta: zorganizuj dokumenty wokół kategorii biznesowych. Jak to zrobić? Jest na to kilka powodów. Język biznesowy to język uniwersalny – jedyny uniwersalny pomiędzy Product Ownerami, Menedżerami Analitykami i Inżynierami. Jako programiści rozwiązujemy problemy biznesowe, prawda? Dlatego by je dobrze rozwiązać musimy mieć podstawową wiedzę na temat tego, co robimy. Podzielenie dokumentacji ze względu na domenę biznesową sprawi, że nawigacja będzie stosunkowo prosta.

Dokumentacja to nie Jira

Dokumentacja nie powinna być powiązana z żadnym zadaniem. Możemy oczywiście wspomnieć o numerze taska w systemach takich jak Jira, jednak w żadnym wypadku nie nazywajcie dokumentu od numeru projektu czy zadania. Fakt: wszystkie taski, projekty i release’y są zapominane po udanym wdrożeniu. Fakt 2: osoby dołączające do zespołu nie będą znały historycznych zadań. Pozwólmy zarządzać projektem specjalistycznym programom (na przykład Jira). W dokumentacji trzymajmy się biznesu – i tyle.

Nowe nawyki

Piszmy dokumentację wcześniej. Jeśli o tym pomyślicie, to już się to dzieje. Zwykle klient, analityk, product owner czy architekt opisuje coś w mailu, notatkach lub na losowej stronie (często w zbiorze o nazwie research). A gdyby tak stworzyć stronę w docelowym miejscu i pracować nad nią wspólnie? Takie rozwiązanie ma same plusy: łatwo się podzielić, łatwo znaleźć, nie potrzebujemy później specjalnie skupiać się na dokumentowaniu problemu czy rozwiązania. Robimy to samo co zawsze – tylko mądrzej.

Kto jest właścicielem?

W naszym wypadku właścicielem są analitycy biznesowi i product ownerzy. Oni wiedzą o zmianach jako pierwsi. Decydują więc o najlepszym miejscu na dokument lub edytują istniejące strony. W ten sposób mamy dobrą, aktualną i darmową dokumentację. Tu istotną opcją jest możliwość pracy z historycznymi wersjami dokumentów (używamy Confluence), jednak wybór jest szeroki. W ten obraz wchodzi również GIT i strony pisane jako Markdown.

Dokumentacja techniczna

Tu jest ciężej. Kod się zmienia. Systemy się zmieniają. Dokumentacja powinna pomagać, a nie być niechcianym obowiązkiem. Jesteśmy zwolennikami samodokumentującego się kodu, jednak akceptujemy fakt, że w dużych systemach to za mało.

C4

C4 to prosty system dokumentacji architektury. Wnosi dużą wartość i jest tani do zarządzania. C4 składa się z czterech diagramów:

• Kontekst – pokazuje nasz system jako pojedynczy bloczek na diagramie. Wokół niego znajdziemy wszystkie nasze integracje – również jako proste bloczki.
• Kontenery – ten diagram to pierwsze zbliżenie na nasz system i jego architekturę. Pokazuje główne obszary platformy. Służy jako swoista mapa systemu.
• Komponenty – jeszcze większe zbliżenie. Pokazuje faktyczne serwisy. W naszym przypadku, dla uproszczenia nawigacji po dużym systemie mamy tych diagramów kilka.
• Klasy – pokazuje konkretne klasy. Poziom niemożliwy do użycia, nikt tej wiedzy nie szuka, jest też niemożliwa do utrzymania.

Tak naprawdę poszliśmy o krok dalej. Używamy większej ilości poziomów. Mamy dziesiątki systemów i dokumentujemy je i ich relacje w kolejnych poziomach. Im wyższy poziom, tym bardziej skupiamy się na problemie biznesowym, a mniej na technologii.

Jak wygląda utrzymanie? Kontekst systemu zmienia się rzadko lub nigdy. Kontenery również nie są zbyt dynamiczne. To poziom komponentów jest najbardziej zmienny, jednak nie są to zmiany codzienne – nie zawsze zmieniamy architekturę systemu.

Oferty pracy z

Architecture Decisions Record

Architecture Decisions Record przechowuje wszystkie decyzje jakie podjęliśmy. Każda z tych decyzji jest opisana z użyciem tego samego szablonu. Każda decyzja ma numer, który odpowiada kolejności, w której została podjęta względem innych dokumentów. Nasz szablon zawiera:

• opis problemu, który mamy,
• status dokumentu (Draft, Approved…),
• wymaganie biznesowe, które jest przyczyną decyzji,
• kontekst – jakie mamy limitacje przy podejmowaniu decyzji?
• opcje do wyboru,
• linki do powiązanych artefaktów.

Jako inżynier doceniam fakt, że ADR wymusza przelanie problemu na tekst. Opisanie problemu i potencjalnych rozwiązań często organizuje myśli i zmusza do refleksji. To z kolei może prowadzić do przedefiniowania oryginalnego problemu, a przynajmniej sprawi, że potencjalne rozwiązania są dobrze przemyślane. Największym plusem jest jednak komunikacja. Zanim spotkam się w sprawie problemu, wysyłam ADR. Oszczędzamy w ten sposób czas na opis problemu na każdym spotkaniu. Jako że dokumenty z decyzją są tworzone przed implementacją, mamy w efekcie darmową dokumentację.

Nowa osoba w projekcie? Przeczytaj ADR. Chcesz dowiedzieć się więcej o architekturze i ewolucji systemu? Poczytaj ADR. Ktoś pyta czemu to tak zrobione? ADR.

Pomyśl o formie

Zawsze odpowiedz sobie na pytanie, co chcesz osiągnąć danym tekstem. To pozwoli Ci również świadomie wybrać formę tekstu. Świetny artykuł znajduje się tu: documentation.divio.com.

Pozostałe strony

Poza wiedzą biznesową i opisem architektury dokumentujemy też inne rzeczy. Mamy jedną stronę, którą nazywamy Jumpstation. Zawiera ona wszystkie linki, które musisz mieć, ale robiłyby bałagan w przeglądarce. Mamy tam odnośniki do narzędzi, repozytoriów, środowisk… Oddzielnie opisujemy też infrastrukturę, komunikację i przechowywanie danych. Te rzeczy się zmieniają, więc dokumentujemy jedynie naszą filozofię, ogólny opis. Każda strona zawiera też link do szczegółów – te z kolei przechowujemy w jedynym miejscu godnym zaufania – w kodzie w repozytorium.

Podsumowanie

Podejście do tworzenia dokumentacji systemów informatycznych sprawdza się u nas od lat. Przygotowałem listę kroków, które musisz wdrożyć, by opisane przeze mnie podejście wdrożyć w Twoim projekcie:     

1. Pomyśl co warto dokumentować w Twoim przypadku. Upewnij się, że rozwiązujesz prawdziwy problem – w innym wypadku jedyne co stworzysz to chaos.
2. Stwórz template kategorii. 
3. Edukuj zespół, żeby zapewnić ciągłość.
4. Zacznij dokumentować po nowemu i twórz dokumenty w obszarach, które aktualnie dotykasz. 

W ten sposób będziesz miał cel, będziesz też powoli do niego zmierzać. Taka podróż może trwać nawet lata. Korzyści również. Jeśli Twój system jest w fazie rozwoju, to jest to najlepszy czas na organizację informacji w logiczny sposób.

Zdjęcie główne artykułu pochodzi z unsplash.com.