dev{tools} - Asciidoctor i Structurizr - dobrana para?

    Asciidoctor to potężne narzędzie do generowania dokumentacji, które wykorzystuje prosty format tekstowy AsciiDoc. W połączeniu z Structurizr, narzędziem do modelowania architektury systemów, Asciidoctor umożliwia tworzenie kompletnej, łatwej w edycji i automatycznie aktualizowanej dokumentacji technicznej, która ewoluuje wraz z rozwojem projektu.

Przykład integracji Asciidoctor ze Structurizr: Workspace DSL z folderem AsciiDoc

W tym przykładzie przedstawiam praktyczne zastosowanie integracji Asciidoctor ze Structurizr w konfiguracji Workspace DSL, gdzie pliki AsciiDoc są wbudowane w strukturę projektu.

Struktura projektu

Zakładamy, że w strukturze projektu znajduje się folder docs przeznaczony na dokumentację AsciiDoc oraz plik workspace.dsl do definiowania modeli w Structurizr.

/projekt
├── /docs
│   ├── index.adoc
│   └── architecture.adoc
├── workspace.dsl
└── ...inne pliki projektu

Przykładowy plik workspace.dsl

W pliku workspace.dsl definiujemy model architektury systemu. Przykład prostego modelu kontekstowego:

workspace {
    model {
        user = person "Użytkownik" {
            description "Osoba korzystająca z systemu"
        }
        
        system = softwareSystem "System aplikacyjny" {
            !docs docs
            description "Aplikacja webowa"

            user -> system "Używa"
        }
    }

    views {
        systemContext system {
            include *
            autolayout lr
        }
        
        theme default
    }
  
}

W tym przykładzie:

• model: Definiujemy model systemu z użytkownikiem oraz aplikacją webową.
• za pomocą dyrektywy !docs wskazujemy folder do dokumentacji
• views: Tworzymy widok kontekstowy systemu, który będzie automatycznie rozmieszczany w układzie lewo-prawo.

Przykładowy plik index.adoc w folderze docs

W pliku index.adoc możemy umieścić opis systemu, informacje o jego architekturze oraz osadzić diagramy wygenerowane przez Structurizr:

= Dokumentacja architektury systemu
Autor: Zespół IT
:date: 2024-09-18

== Wprowadzenie

Ten dokument opisuje architekturę naszego systemu aplikacyjnego.

== Diagram kontekstowy

Poniżej znajduje się diagram kontekstowy, który pokazuje głównych uczestników systemu i ich interakcje:

image::system[]

Kroki do uruchomienia projektu

1. Tworzenie modelu architektury: Zdefiniuj w pliku workspace.dsl model systemu, który chcesz odwzorować w diagramach.
2. Dodanie dokumentacji: Umieść pliki AsciiDoc w folderze docs, które będą dokumentować poszczególne elementy systemu.
3. Integracja z narzędziem do CI/CD: Automatycznie generuj dokumentację i aktualizuj ją na podstawie zmian w modelu architektury za pomocą narzędzi CI/CD.
1. Generowanie do formatów typu pdf html
2. Importowanie do Confluence
3. Utrzymywanie w środowisku Structurizr - OnPremises lub Cloud Service o czym niedługo :) 

Korzyści z integracji Asciidoctor i Structurizr

• Automatyczna aktualizacja dokumentacji: Gdy model architektury w Structurizr zmienia się, dokumentacja w Asciidoctor jest automatycznie aktualizowana.
• Spójność dokumentacji: Dzięki Asciidoctor dokumentacja pozostaje zwięzła, czytelna i zawsze aktualna.
• Elastyczność formatów: Dokumentację stworzoną w Asciidoctor można wyeksportować do różnych formatów (HTML, PDF), co czyni ją wszechstronną i łatwo dostępną.

Podsumowanie

Integracja Asciidoctor z Structurizr w ramach Workspace DSL to potężne narzędzie, które umożliwia zespołom IT efektywne tworzenie i zarządzanie dokumentacją techniczną. Dzięki tej integracji, zespoły mogą na bieżąco aktualizować dokumentację, zapewniając jej spójność z modelem architektury systemu, co znacznie ułatwia pracę i zwiększa efektywność projektu.