Dokumentacja jako kod

 W dzisiejszym dynamicznym świecie IT, efektywne zarządzanie dokumentacją projektową jest kluczowe. Pojęcie "Documentation as a  Code" (DaC) zyskuje na popularności jako sposób na ułatwienie tego procesu. W tym artykule przyjrzymy się, jak DaC rewolucjonizuje sposób, w jaki tworzymy i utrzymujemy dokumentację, oraz jak łatwo można to osiągnąć za pomocą Structurizr DSL i PlantUML.

Czym jest Dokumentacja jako Kod?

"Dokumentacja jako Kod" to podejście, które traktuje dokumentację tak samo jak kod źródłowy. Oznacza to, że dokumentacja jest przechowywana w repozytoriach kodu, podlega przeglądom kodu, korzysta z systemów kontroli wersji i jest ciągle aktualizowana wraz z rozwojem projektu.

Korzyści z DaC

• Spójność: Dokumentacja aktualizowana jest równolegle z kodem, co zapewnia jej spójność i aktualność.
• Współpraca: Ułatwia współpracę w zespole, dzięki wykorzystaniu narzędzi znanych deweloperom, takich jak Git.
• Automatyzacja: Możliwość automatyzacji procesów, takich jak generowanie dokumentacji API.

Narzędzia wspierające DaC

Popularne narzędzia wspierające ten proces to m.in. Markdown dla łatwej edycji tekstu, Git do kontroli wersji, oraz narzędzia takie jak Structurizr DSL i PlantUML do wizualizacji architektury systemów.

Użycie Structurizr DSL i PlantUML

Structurizr DSL to narzędzie do definiowania modeli architektonicznych w formie plików tekstowych. PlantUML to narzędzie do tworzenia diagramów z kodu. Połączenie tych narzędzi z DaC może znacznie poprawić jakość dokumentacji architektonicznej.

Przykład Projektu Structurizr DSL

Stworzymy pliki DSL, aby zdefiniować nasz model architektoniczny, a także włączymy dokumentację w Markdown oraz diagramy PlantUML.

1. Struktura Projektu

project/
│
├── src/
│   ├── system.dsl
│   └── diagrams/
│       └── system.puml
└── docs/
    └── documentation.md

2. Plik system.dsl

workspace {

    model {
        user = person "Użytkownik" {
            description "Opis użytkownika"
        }
        
        softwareSystem = softwareSystem "System" {
            !docs ../docs/documentation.md
            description "Opis systemu"
            
            user -> softwareSystem "Używa"
        }
    }
    
    views {
        
        properties {
            "plantuml.url" "http://localhost:7777"
            "plantuml.format" "svg"
        }

        systemContext softwareSystem {
            include *
            autolayout lr
        }
        
        image component1 {
            plantuml diagrams/system.puml
            title "Class diagram for Component1"
        }
        theme default
    }
    
    
}

3. Plik system.puml




@startuml
actor Użytkownik
rectangle System {
    Użytkownik --> (Używa)
}
@enduml

4. Plik documentation.md




# Przegląd systemu

Opis szczegółowy systemu.

Generowanie Dokumentacji

Aby wygenerować dokumentację i diagramy, wystarczy użyć Structurizr CLI:

structurizr-cli export -workspace src/system.dsl -format json

Dzięki temu podejściu, dokumentacja jest zawsze aktualna i spójna z kodem, co jest
 kluczowe w dynamicznie zmieniającym się środowisku IT.

Wyzwania i Jak Im Sprostać

Mimo wielu zalet, DaC wymaga zmiany myślenia i może być wyzwaniem dla zespołów przyzwyczajonych do tradycyjnych metod. Kluczowe jest szkolenie zespołów i stopniowe wprowadzanie DaC, aby każdy mógł się z nim oswoić.

Podsumowanie

"Dokumentacja jako Kod" to podejście, które może znacznie poprawić jakość i efektywność dokumentacji w projektach IT. Poprzez integrację z procesami deweloperskimi, DaC umożliwia tworzenie bardziej aktualnej, spójnej i użytecznej dokumentacji. Użycie narzędzi takich jak Structurizr DSL i PlantUML dodatkowo wzbogaca dokumentację, czyniąc ją bardziej wizualną i zrozumiałą dla całego zespołu.