w dniu
dev
devops
platform_engineering
security
- Pobierz link
- X
- Inne aplikacje
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.
"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.
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.
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.
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. Pliksystem.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 {
theme default } }plantuml diagrams/system.puml title "Class diagram for Component1" }
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.
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.
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ć.
"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.
Komentarze
Prześlij komentarz