Wzorce MSA: Retry Logic

w dniu
0

EA - Dokumentacja Nie Musi Być Nudna: Wprowadzenie do Documentation as Code"

w dniu

    Czy tworzenie dokumentacji mus być nudnym i najczęściej pomijanym obowiązkiem? Większość z nas tak to widzi. Ale co, jeśli powiem Ci, że może stać się integralną częścią Twojego workflow, dynamiczną, w pełni zautomatyzowaną i dostosowaną do potrzeb zespołu? Takie podejście jest możliwe dzięki filozofii Documentation as Code (Docs as Code), którą omówiłem w artykule „Dokumentacja jako Kod”.



Czym jest Documentation as Code?

Docs as Code to podejście, które traktuje dokumentację w taki sam sposób, jak kod źródłowy aplikacji. Oznacza to, że:

  • Dokumentacja znajduje się w tych samych repozytoriach co kod.
  • Wykorzystuje się narzędzia takie jak Git do wersjonowania i wspólnej pracy.
  • Proces tworzenia i aktualizacji dokumentacji jest zintegrowany z pipeline CI/CD.

Tym samym dokumentacja przestaje być statycznym artefaktem, a staje się dynamicznym elementem Twojego projektu, który może być automatycznie generowany i aktualizowany.

Zalety podejścia Docs as Code

  1. Automatyzacja Dzięki narzędziom takim jak PlantUML, Structurizr, czy arc42, możesz generować dokumentację bezpośrednio z kodu i repozytoriów. Na przykład:

    • Modele UML mogą być automatycznie tworzone na podstawie kodu źródłowego.
    • Struktura systemu generowana z plików DSL, takich jak Structurizr DSL.

    Automatyzacja eliminuje ręczne pisanie dokumentacji i pozwala skupić się na tworzeniu oprogramowania.

  2. Integracja z CI/CD Dokumentacja może być automatycznie aktualizowana za każdym razem, gdy kod zmienia się w repozytorium. W pipeline CI/CD możesz dodać kroki takie jak:

    • Generowanie modeli i diagramów.
    • Publikacja dokumentacji na wewnętrznych portalach lub w serwisach takich jak GitHub Pages.
    • Automatyczne sprawdzanie poprawności składni i zgodności dokumentów.

  3. Współpraca Wykorzystanie narzędzi takich jak Git umożliwia wspólną pracę nad dokumentacją:

    • Każdy członek zespołu może zgłaszać propozycje zmian za pomocą pull requestów.
    • Historia zmian jest przejrzysta i łatwa do śledzenia.
    • Możesz używać tych samych narzędzi i procesów co w przypadku kodu (np. code review).

  4. Spójność Dokumentacja zawsze odzwierciedla aktualny stan projektu, co minimalizuje ryzyko błędów i niespójności. Jeśli coś się zmienia w kodzie, zmiana ta może automatycznie wpłynąć na generowaną dokumentację.

Jak wdrożyć Documentation as Code?

1. Wybierz narzędzia

  • PlantUML: Do generowania diagramów UML (sekwencji, klas, komponentów itp.) bezpośrednio z plików tekstowych.
  • Structurizr: Do modelowania architektury w stylu C4, z możliwością integracji z kodem.
  • arc42: Do dokumentowania architektury systemu w uporządkowany i spójny sposób.
  • Asciidoctor lub Markdown: Do tworzenia dokumentacji tekstowej w lekkim formacie, który łatwo można przetworzyć na HTML lub PDF.

2. Zintegruj dokumentację z pipeline CI/CD

  • Skonfiguruj kroki w CI/CD, które generują i publikują dokumentację.
  • Użyj narzędzi takich jak GitHub Actions, GitLab CI, czy Jenkins do automatyzacji procesu.

3. Twórz dokumentację jako kod

  • Zamiast pisać statyczne dokumenty, zapisuj dane w formacie tekstowym (np. DSL, Markdown).
  • Korzystaj z automatycznych generatorów, które przekształcą te dane w finalne dokumenty.

4. Uczyń dokumentację częścią workflow

  • Dokumentację aktualizuj razem z kodem – każda zmiana funkcjonalności powinna być odzwierciedlona w dokumentacji.
  • Wymagaj aktualizacji dokumentacji jako elementu procesu przeglądu kodu (code review).

Przykład praktyczny – Integracja z CI/CD

Załóżmy, że tworzysz dokumentację architektury systemu przy użyciu Structurizr DSL i Asciidoctor. Możesz skonfigurować pipeline CI/CD w następujący sposób:

  1. Etap 1: Generowanie diagramów
    Uruchom skrypt generujący diagramy na podstawie plików DSL.


    structurizr-cli export -workspace workspace.dsl -format plantuml

  2. Etap 2: Tworzenie dokumentacji
    Użyj Asciidoctor, aby wygenerować dokument HTML lub PDF.


    asciidoctor -b html5 dokumentacja.adoc

  3. Etap 3: Publikacja
    Opublikuj wygenerowaną dokumentację w serwisie takim jak GitHub Pages lub serwerze wewnętrznym.

Podsumowanie

Podejście Documentation as Code zmienia sposób, w jaki patrzymy na dokumentację – z nudnego obowiązku na integralną część procesu tworzenia oprogramowania. Dzięki automatyzacji, integracji z pipeline CI/CD i wspólnej pracy nad dokumentami, dokumentacja staje się dynamiczna, aktualna i spójna z projektem.


Zapraszam do kontaktu i rezerwacji terminów na warsztaty oraz konsultacje. Razem usprawnimy Twoje procesy dokumentacyjne i architektoniczne!

Więcej na stronie: 

https://softwareveteran.dev/#offer


Komentarze

Prześlij komentarz