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, iż ten czas do Was wróci. Niestety bazy wiedzy mają tę specyfikę, iż same stają się drogie, jeżeli 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żeli 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żeli 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, iż 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żeli 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, iż 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.
