Od diagramów do żyjącej dokumentacji: Przewodnik dla początkujących w zakresie potoku DevOps Visual Paradigm

Wprowadzenie: Koniec z przestarzałą dokumentacją

Jeśli kiedykolwiek pracowałeś nad projektem oprogramowania, wiesz, jak bolesne jest „dłużne dokumentowanie”. Spędzasz godziny rysując piękne diagramy architektury w Visio lub Lucidchart, by zobaczyć, jak one natychmiast stają się bezradnie przestarzałe, gdy zespół deweloperski zmienia schemat bazy danych lub dodaje nowy mikroserwis. Dokumentacja staje się obowiązkiem, a programiści przestają jej ufać.

Wprowadźmy Żyjąca dokumentacja—paradygmat, w którym Twoja dokumentacja jest automatycznie generowana, ciągle aktualizowana i doskonale zsynchronizowana z rzeczywistym kodem źródłowym.

Ten samouczek pokaże Ci, jak tworzyć Potok DevOps i dokumentacji Visual Paradigm (VP). Przekształcimy statyczne modele wizualne w zautomatyzowaną, żyjącą bazę wiedzy. Na końcu tego przewodnika zrozumiesz, jak połączyć narzędzia do projektowania na komputerze, asystentów AI oraz potoki CI/CD, aby stworzyć płynny cykl życia „żyjącej dokumentacji”.

Zalecane narzędzia i wymagania wstępne

Aby śledzić ten potok, potrzebujesz dostępu do ekosystemu Visual Paradigm oraz standardowych narzędzi DevOps:

1. Visual Paradigm Desktop lub Online: Do tworzenia bogatych diagramów UML, SysML i BPMN.

2. Asystent VP Chatbot / AI: Do generowania początkowych diagramów przy użyciu zapytań w języku naturalnym.

3. Git: Do kontroli wersji Twoich modeli tekstowych i kodu.

4. Platforma CI/CD: GitHub Actions, GitLab CI lub Jenkins (w tym samouczku użyjemy GitHub Actions).

5. OpenDocs / PlantUML: Do renderowania modeli tekstowych w wyjścia wizualne.

Faza 1: Warstwa projektowa (zachwytywanie architektury)

Potok zaczyna się tam, gdzie zapisujesz wymagania i projektujesz architekturę systemu. Visual Paradigm oferuje trzy główne sposoby tworzenia modeli:

• VP Desktop: Mocne narzędzie z pełnymi możliwościami do złożonych architektur przedsiębiorstw, UML i BPMN.

• VP Online: Narzędzie oparte w chmurze, wspierające współpracę, idealne do szybkich grafik wektorowych i planowania agilnego.

• VP Chatbot / AI: Interfejs rozmówczy, który generuje diagramy bezpośrednio z opisów tekstowych lub historii użytkownika.

Prawdopodobny przykład: Projektowanie przepływu płatności w sklepie internetowym

Wyobraź sobie, że zostajesz poproszony o zaprojektowanie architektury płatności dla nowej platformy e-commerce. Zamiast ręcznie przeciągać i upuszczać kształty, możesz użyć VP Chatbot z następującym monitem:

„Wygeneruj diagram składników dla systemu płatności e-commerce. Powinien zawierać interfejs WWW, usługę zamówień, bramę płatności oraz bazę danych zapasów.”

AI natychmiast generuje diagram strukturalny. W tle ten model wizualny może być reprezentowany przy użyciu standardowej składni tekstowej, takiej jak PlantUML, która jest domyślnie obsługiwana przez Visual Paradigm w celu obsługi funkcji modelowania tekstowego.

Oto kod PlantUML przedstawiający nasz projekt wygenerowany przez AI:

@startuml Architektura płatności e-commerce
!theme plain
skinparam componentStyle rectangle

package "Warstwa frontendu" {
  [Aplikacja WWW] jako Web
  [Aplikacja mobilna] jako Mobile
}

package "Microserwisy backendu" {
  [Usługa zamówień] jako Order
  [Brama płatności] jako Payment
  [Usługa zapasów] jako Inventory
}

database "PostgreSQLn(Baza danych zapasów)" jako DB

' Relacje
Web --> Order : interfejs REST API
Mobile --> Order : interfejs REST API
Order --> Payment : Przetwarzanie transakcji
Order --> Inventory : Sprawdzenie/Zarezerwowanie towaru
Inventory --> DB : Odczyt/Zapis

@enduml

Faza 2: Warstwa abstrakcji (VPasCode)

Modele wizualne są świetne dla ludzi, ale maszyny potrzebują tekstu. To właśnie tutaj VPasCode (Visual Paradigm jako kod) mostuje tę przerwę.

VPasCode pozwala traktować Twoje diagramy dokładnie tak, jak kod oprogramowania.

• Modelowanie tekstowe: Definiujesz diagramy przy użyciu czytelnych dla człowieka tekstów (takich jak kod PlantUML powyżej).

• Kontrola wersji: Zapisujesz te definicje diagramów jako .puml lub .vpuc pliki bezpośrednio w twoim repozytorium Git obok kodu aplikacji.

• Automatyzacja za pomocą SDK/CLI: Możesz używać interfejsów API Visual Paradigm do programistycznego pobierania lub modyfikowania elementów wizualnych.

Prawdopodobny przykład: przesyłanie do Git

Zamiast zapisywać swój diagram jako izolowane .pngplik, zapisujesz kod PlantUML do pliku o nazwie checkout-architecture.puml w folderze projektu /docs/architektura/ folder.

git add docs/architektura/checkout-architecture.puml
git commit -m "docs: dodaj początkowy diagram architektury checkout"
git push origin main

Teraz diagram jest kontrolowany wersjami. Jeśli deweloper zmienia usługę Order, aktualizuje plik tekstowy w tym samym żądaniu zmiany.

Faza 3: Warstwa automatyzacji (OpenDocs i CI/CD)

To jest miejsce, gdzie dzieje się magia. Nie eksportujemy już ręcznie diagramów do formatu PDF lub Word. Automatyzujemy ten proces przy użyciu OpenDocs i potoku CI/CD.

• OpenDocs: Otwarta platforma generowania dokumentacji, która odczytuje dane modelu (pliki PlantUML/VPasCode) i mapuje je na szablony tekstowe.

• Integracja z potokiem: Wykorzystujemy narzędzia CI/CD (takie jak GitHub Actions), aby nasłuchiwać zmian w repozytorium.

• Automatyczne wyzwalacze: Za każdym razem, gdy kod lub modele ulegają zmianie, potok automatycznie ponownie generuje dokumentację.

Prawdopodobny przykład: Przepływ pracy GitHub Actions

Oto realistyczny .github/workflows/build-docs.yml plik, który wywołuje się za każdym razem, gdy pliki architektury są aktualizowane. Używa PlantUML do renderowania diagramów i pakuje je do statycznego strony HTML.

name: Buduj żywy dokument

# Wyzwal przepływ pracy tylko wtedy, gdy pliki w folderze docs/architektura ulegną zmianie
on:
  push:
    paths:
      - 'docs/architektura/**'
  workflow_dispatch: # Pozwala na ręczne wyzwalanie

jobs:
  generate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Sklonuj repozytorium
        uses: actions/checkout@v3

      - name: Skonfiguruj Java (wymagane dla PlantUML/VP CLI)
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Generuj diagramy za pomocą OpenDocs/PlantUML
        run: |
          # Pobierz plik jar PlantUML
          wget https://github.com/plantuml/plantuml/releases/download/v1.2023.10/plantuml-1.2023.10.jar -O plantuml.jar
          # Renderuj wszystkie pliki .puml w katalogu architektury do formatu SVG/PNG
          java -jar plantuml.jar -tsvg docs/architektura/*.puml

      - name: Skompiluj HTML dokumentu żywego
        run: |
          # Zakładając niestandardowy skrypt OpenDocs lub polecenie CLI VP do otoczenia obrazów w szablonach HTML
          mkdir -p public/docs
          cp -r docs/architektura/*.svg public/docs/
          # Wygeneruj index.html z metadane i osadzonymi diagramami
          echo "<html><body><h1>Żywy dokument architektury</h1>" > public/docs/index.html
          echo "<img src='checkout-architektura.svg' />" >> public/docs/index.html
          echo "</body></html>" >> public/docs/index.html

      - name: Wdróż na GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Faza 4: Warstwa wyjściowa (Żywy dokument)

Ostatecznym produktem tego potoku jest Twój Żywy dokument. Ponieważ jest generowany automatycznie z źródła prawdy (Twój kod i modele tekstowe), nigdy nie wygasa.

• Jedno źródło prawdy: Kod, modele wizualne i wyjaśnienia tekstowe pozostają doskonale zsynchronizowane.

• Elastyczność formatów: Pipeline może generować responsywne strony internetowe w formacie HTML (hostowane na GitHub Pages lub wewnętrznych wiki), pliki PDF do celów zgodności lub bezpośrednio przesyłać do Confluence.

• Dynamiczne metadane: Zaawansowane konfiguracje mogą osadzać aktywne metryki systemu, słowniki danych oraz śledzenie wymagań Jira bezpośrednio w wygenerowanym tekście przeznaczonym dla użytkownika.

Twój zespół ma teraz piękny, aktualny adres URL (np. docs.twojaprzewozowa.com) który zawsze odzwierciedla dokładny aktualny stan oprogramowania.

Krok po kroku: Przepływ wdrożenia

Podsumowując, oto dzienny przepływ pracy, jaki będzie realizował Twój zespół w celu utrzymania tego ekosystemu:

1. Projekt: Utwórz diagram klasy UML, komponentu lub procesu BPMN w VP Desktop/Online lub wywołaj chatbot VP, aby wygenerować go na podstawie historii użytkownika.

2. Eksport: Zapisz lub zatwierdź plik projektu przy użyciu formatów tekstowych VPasCode/PlantUML w repozytorium Git projektu.

3. Budowa: Wypchnij zmiany do Git. Ta akcja automatycznie uruchamia Twój pipeline CI/CD (np. GitHub Actions).

4. Generuj: Pipeline uruchamia OpenDocs/PlantUML w celu wyodrębnienia nowych obrazów diagramów, skompilowania metadanych oraz wygenerowania wyjść w formacie HTML/PDF.

5. Publikuj: Narzędzie wdraża świeżo zaktualizowany żywy dokument do portalu zespołu wewnętrznego, wiki lub publicznej strony dokumentacji.

Wnioski: Przyjęcie mentalności żywej dokumentacji

Przejście na wizualny model pipeline DevOps wymaga zmiany nastawienia. Dokumentacja nie jest już postrzegana jako poślednia myśl ani osobne zadanie przypisane młodemu programiście na końcu sprintu. Zamiast tego staje się automatycznym produktem procesu rozwojowego.

Wykorzystując Warstwę projektowania (VP Desktop i AI), Warstwę abstrakcji (VPasCode), Warstwę automatyzacji (CI/CD i OpenDocs) oraz Warstwa wyjściowa (Dokument żywy), po raz ostatni eliminujesz dług dokumentacji. Twoje schematy wreszcie będą się rozwijać z tą samą szybkością co kod, zapewniając Twojej drużynie wiarygodny, jedyny źródłowy punkt prawdy, który wspiera lepsze podejmowanie decyzji i szybsze włączanie do pracy.

Zacznij od małego: wybierz jedną kluczową mikro-usługę, napisz jej architekturę w PlantUML, zatwierdź ją w Git, a następnie skonfiguruj podstawową akcję GitHub, aby ją wyrenderować. Kiedy po raz pierwszy zobaczysz, jak Twój pierwszy „żywy dokument” automatycznie się aktualizuje, już nigdy nie chcesz wrócić do ręcznego tworzenia schematów.

Dokumentacja

1. Studium przypadku: Przyspieszanie dokumentacji architektury oprogramowania za pomocą VPasCode – rewolucja Diagram-as-Code: Studium przypadku dotyczące tego, jak VPasCode mostuje luki między kodem a wizualizacją dzięki gotowemu do AI Diagram-as-Code i automatycznej inżynierii układu.
2. Kompleksowy przewodnik po VPasCode od Visual Paradigm: szczegółowy przegląd filozofii głównej VPasCode, interfejsu użytkownika, wsparcia dla wielu silników oraz przepływów współpracy.
3. Od kodu do przejrzystości: Przewodnik dla początkujących do płynnego tworzenia schematów z VPasCode i OpenDocs: Poradnik dotyczący korzystania z VPasCode w połączeniu z OpenDocs do dokumentacji wspieranej przez AI, w tym praktyczne przykłady PlantUML i integracja z pipeline.
4. Opanowanie VPasCode: Ostateczny przewodnik po Diagram-as-Code z obsługą AI i wieloma silnikami: Zaawansowany przewodnik omawiający unikalne zalety VPasCode, architekturę natively wspierającą AI oraz wsparcie dla wielu silników.
5. Rewolucja w utrzymaniu schematów: Jak automatyczna poprawka AI w VPasCode eliminuje frustracje związane z składnią: Głęboka analiza funkcji automatycznej poprawki opartej na AI w VPasCode, służącej do automatycznego wykrywania i poprawiania błędów składniowych.
6. Jak czatbot AI Visual Paradigm i VPasCode działają jako zintegrowany ekosystem do tworzenia schematów: Wyjaśnia zintegrowany dwufazowy przepływ pracy łączący czatbot AI do szybkiego generowania i VPasCode do precyzyjnej poprawy schematów.
7. Przejrzystość przez projektowanie: Uproszczenie dokumentacji infrastruktury za pomocą VPasCode i języka Graphviz DOT: Studium przypadku dotyczącego wykorzystania VPasCode i języka DOT Graphviz do modernizacji dokumentacji infrastruktury jako kodu.
8. VPasCode: Zintegrowana platforma Diagram-as-Code: Oficjalna strona funkcji z szczegółowym opisem obsługiwanych typów schematów, wsparcia dla wielu silników, podglądu w czasie rzeczywistym oraz możliwości eksportu.