Diagram architektury na stronie SharePoint został stworzony w 2009 roku. Był wtedy dokładny, odzwierciedlał system w stanie, w jakim istniał w momencie dużej migracji platformy. Stworzony przez architekta, który spędził trzy tygodnie na dokumentowaniu każdego komponentu i jego powiązań. Od 2009 roku system otrzymał około 4,800 zatwierdzeń, w jego rozwój zaangażowało się piętnaście zespołów, cztery z komponentów przedstawionych na diagramie już nie istnieją, dodano jedenaście nowych komponentów, które nigdy nie zostały przedstawione na diagramie, a architekt, który go stworzył, przeszedł na emeryturę w 2016 roku. Diagram nadal istnieje. Gdy dołącza nowy programista i pyta „jak działa system?”, ktoś wysyła mu link do SharePoint. Diagram nie jest dokumentacją. To archeologia.
Dług dokumentacyjny to dług techniczny odnoszący się do warstwy dokumentacji: narastająca luka między tym, co dokumentacja mówi o systemie, a tym, co system faktycznie robi. Dryf architektoniczny, w którym diagramy odłączają się od systemów, które przedstawiają, jest najczęstszą i najniebezpieczniejszą formą długu dokumentacyjnego. Jest on najniebezpieczniejszy, ponieważ rodzi fałszywe poczucie pewności: diagram, który istnieje i wygląda profesjonalnie, sprawia, że interesariusze mają wrażenie, że system jest zrozumiały, podczas gdy w rzeczywistości widzą jedynie historyczny artefakt opisujący system, który w przedstawionej formie już nie istnieje. Nieaktualne diagramy są gorsze niż brak diagramów, ponieważ brak diagramów skłania ludzi do odkrycia tego, co faktycznie istnieje; nieaktualne diagramy skłaniają ludzi do działania w oparciu o to, co już nie jest prawdą.
Dokumentacja bez wysiłku
SMART TS XL tworzy dziennik zmian każdej modyfikacji programu, zależności i kopii od czasu poprzedniego przebiegu analizy.
DOWIEDZ SIĘ WIĘCEJ…Pięć mechanizmów, które powodują, że diagramy stają się nieaktualne
W każdym artykule na temat dryfu dokumentacji czytamy, że „diagramy z czasem tracą na aktualności”. Prawie żaden nie wyjaśnia konkretnych mechanizmów, które to powodują. Zrozumienie tych mechanizmów jest warunkiem koniecznym, aby im zapobiegać, ponieważ różne mechanizmy wymagają różnych strategii prewencyjnych.
1. Problem kumulującej się delty. Diagram to migawka systemu w danym momencie. Każda zmiana kodu po tej migawce to delta między diagramem a rzeczywistością. Poszczególne delty są zazwyczaj niewielkie – to nowa usługa, zmieniona nazwa komponentu, dodana zależność. Każdą z nich łatwo udokumentować w izolacji. Problem polega na tym, że nikt nie dokumentuje ich stopniowo, ponieważ aktualizacja diagramu dla każdej zmiany jest postrzegana jako narzut bez natychmiastowych korzyści. Po 100 niezarejestrowanych deltach diagram jest zasadniczo błędny. Po 1,000 staje się w zasadzie fikcją.
2. Problem brakującego pochodzenia. Diagram, który nie ma programowego powiązania z kodem, który przedstawia, nie ma mechanizmu wykrywania, kiedy staje się niedokładny. Nie ma sygnału, który uruchamia się, gdy zmiana w bazie kodu zaprzecza stwierdzeniu zawartemu na diagramie. Diagram i kod to niepowiązane artefakty, które przypadkiem opisują ten sam system, ale połączenie istnieje tylko w umysłach osób, które narysowały diagram, i tylko tak długo, jak te osoby go pamiętają.
3. Problem dryfu własności. Diagramy architektury są zazwyczaj tworzone przez konkretną osobę w określonym momencie. Kiedy ta osoba odchodzi, ukryta wiedza, która sprawiła, że diagram był dokładny, zrozumienie tego, które komponenty zostały celowo pominięte, które relacje zostały uproszczone, które etykiety były skrótami dla czegoś bardziej złożonego, odchodzi wraz z nią. Nowy opiekun diagramu dziedziczy artefakt, którego nie stworzył, może nie w pełni go rozumieć i nie ma motywacji do utrzymywania go w oparciu o bazę kodu, której nie zaprojektował.
4. Problem zaniku nadmiernej precyzji. Diagramy zawierające zbyt wiele szczegółów tracą aktualność szybciej niż diagramy prezentujące odpowiednią abstrakcję. Diagram przedstawiający każdą mikrousługę, każdy punkt końcowy API i każdą tabelę bazy danych wymaga aktualizacji dla każdego wdrożenia. Diagram przedstawiający domeny usług i ich podstawowe wzorce interakcji wymaga aktualizacji tylko wtedy, gdy zmieniają się granice domen. Diagramy nadmiernie precyzyjne mają okres półtrwania nieaktualności mierzony w sprintach; diagramy odpowiednio abstrakcyjne mają okres półtrwania nieaktualności mierzony w kwartałach.
5. Problem blokady formatu. Diagramów zapisanych jako pliki Visio, slajdy PowerPoint, eksporty PNG lub załączniki PDF nie można generować, weryfikować ani porównywać programowo. Nie ma możliwości zadania pytania „czy ten diagram nadal pasuje do kodu?”, ponieważ diagram jest obrazem pikselowym, a kod tekstem. Wybór formatu dokonany podczas tworzenia diagramu decyduje o tym, czy diagram będzie kiedykolwiek mógł zostać zweryfikowany w systemie, który przedstawia.
Katastrofa dokumentacji systemu legacy
W przypadku nowoczesnych systemów chmurowych z aktywnymi zespołami programistycznymi, nieaktualność diagramów stanowi problem zarządzania, który można rozwiązać za pomocą praktyk architektury jako kodu, narzędzi do tworzenia żywej dokumentacji i dyscypliny inżynierskiej. System często się zmienia; diagram można zaktualizować, aby go dostosować, jeśli proces jest prawidłowy.
W przypadku starszych systemów problem jest innego rodzaju, a nie tylko stopnia.
Diagram architektury sporządzony podczas przeglądu projektu systemu mainframe w 1992 roku mógł zawierać 30 lat zmian w kodzie od momentu jego powstania. Każdy rok aktywnej konserwacji złożonego portfolio COBOL generuje setki commitów, dodawane są nowe programy, wycofywane stare programy, aktualizowane są kopie zapasowe, a strumienie zadań JCL są reorganizowane. Diagram z 1992 roku był wówczas dokładny. Z każdym kolejnym rokiem jego dokładność stopniowo maleje. Do 2026 roku różnica między diagramem a systemem może być większa niż w przypadku samego systemu oryginalnego – istnieje więcej nowych programów, których nie ma na diagramie, niż programów z systemu oryginalnego, które nadal działają zgodnie z pierwotnym projektem.
To, co czyni ten problem katastrofalnym, a nie tylko niewygodnym, to sposób wykorzystania diagramu. Kiedy zespół modernizacyjny przybywa, aby ocenić system, nie wie, że diagram jest błędny. Nie ma możliwości stwierdzenia, jak bardzo jest błędny. Diagram wygląda profesjonalnie. Zawiera pola komponentów, strzałki relacji i adnotacje. Sugeruje to, że ktoś rozumiał ten system na tyle dobrze, aby go narysować. Zespół wykorzystuje go jako punkt wyjścia, a każda analiza oparta na błędnym punkcie wyjścia prowadzi do błędnych wniosków.
Model audytu Docuwriter jasno to ujmuje: właściwy audyt dokumentacji „zamienia niejasne obawy w fakty podlegające inspekcji”. W przypadku starszych systemów audyt dokumentacji niemal zawsze prowadzi do tego samego wniosku: diagramy są albo nieobecne, albo tak stare, że reprezentują system, który nie istniał od lat. Fakty podlegające inspekcji, gdy w końcu się pojawią, opisują system zasadniczo różniący się od tego, na którym ktokolwiek pracował.
Konkretny tryb awarii: zespół modernizacyjny szacuje zakres migracji na podstawie diagramu z 1992 roku. Przedstawia on 180 komponentów. Analiza strukturalna rzeczywistej bazy kodu ujawnia 340 programów, z których 80 to martwy kod, a kolejne 40 zostało dodanych po 1992 roku i nigdy nie zostało przedstawionych na diagramach. Oszacowanie zakresu było błędne o współczynnik dwa przed napisaniem pierwszej linijki nowego kodu.
Kategorie diagramów według wskaźnika nieświeżości
Nie wszystkie diagramy tracą aktualność w tym samym tempie. Szybkość utraty aktualności zależy od tego, co przedstawia diagram, jak często zmieniają się przedstawione elementy i jak precyzyjnie diagram je przedstawia.
| Typ diagramu | Co często się zmienia | Wskaźnik nieświeżości | Priorytet łagodzenia |
|---|---|---|---|
| Inwentarz usług/komponentów | Dodano nowe usługi, wycofano stare usługi | Wysoki | Krytyczne — najwyższa częstotliwość zmian |
| Mapa zależności/integracji | Dodano interfejsy API, zmieniono integracje, zmodyfikowano przepływy danych | Wysoki | Krytyczne — każde wdrożenie może to zmienić |
| Model danych / ERD | Zmiany schematu, nowe tabele, modyfikacje kolumn | Średni wzrost | Wysoki — zmiany schematu są częste w aktywnym rozwoju |
| Diagramy sekwencji | Zmiany logiki biznesowej, aktualizacje kontraktów API | Średni | Wysoki — każda zmiana przepływu pracy unieważnia te |
| Infrastruktura / wdrożenie | Infrastruktura jako kod powoduje częste zmiany | Wysoki | Średni — narzędzia IaC mogą generować je automatycznie |
| Domena / kontekst ograniczony | Zmiany organizacyjne i własnościowe | Średnio zaawansowany | Niska — granice domen zmieniają się kwartalnie lub rzadziej |
| Rejestry decyzji (ADR) | Rzadko się zmieniają (decyzje są historyczne) | bardzo niski | Niski — po prawidłowym zarejestrowaniu pozostaje dokładny |
| Wykres wywołań programu (COBOL) | Każda zmiana kodu potencjalnie to zmienia | Bardzo wysoka | Krytyczne dla dziedzictwa — zmiany niewidoczne |
| Zeszyt ćwiczeń / schemat (COBOL) | Każda zmiana FD wpływa na wiele programów | Wysoki | Krytyczne dla dziedzictwa — zmiany następują kaskadowo w sposób cichy |
Dwa dolne wiersze zawierają wpisy specyficzne dla starszych wersji, których nie uwzględnia żadna standardowa dokumentacja. Graf wywołań programu COBOL może zostać unieważniony przez każdą zmianę kodu dowolnego programu w drzewie wywołań. Kopiarka współdzielona przez 200 programów jest unieważniana dla każdego programu, gdy zmienia się kopiarka. Te diagramy charakteryzują się najwyższym wskaźnikiem nieaktualności w portfolio przedsiębiorstwa i najpoważniejszymi konsekwencjami nieaktualności, ponieważ programy, które opisują, obsługują najważniejsze procesy biznesowe.
Rozwiązanie problemu pochodzenia: śledzenie diagramów do ich źródła
Podstawową przyczyną braku dokumentacji nie jest brak procesu aktualizacji dokumentacji. Jest nim brak pochodzenia, czyli możliwego do prześledzenia powiązania między elementem diagramu a artefaktem kodu, który on przedstawia. Bez pochodzenia nie ma mechanizmu wykrywania nieaktualności. Dzięki pochodzeniu wykrywanie nieaktualności jest automatyczne: jeśli artefakt kodu zmienił się od momentu wygenerowania diagramu, diagram jest nieaktualny.
Pochodzenie w dokumentacji występuje na dwóch poziomach:
Pochodzenie statyczne Dokumentacja generowana z kodu w określonym momencie, ze znacznikiem czasu generacji i odniesieniem do stanu kodu (skrót zatwierdzenia, wersja, data analizy), który dokumentacja odzwierciedla. Statyczne pochodzenie nie zapobiega nieaktualności, ale umożliwia jej wykrycie: znacznik czasu wskazuje, że dokumentacja została wygenerowana z zatwierdzenia. abc123 w określonym dniu, a bieżące zatwierdzenie to def456 w późniejszym terminie. Luka między dwoma zatwierdzeniami to luka między dokumentacją a obecnym kodem.
Dynamiczna proweniencja to dokumentacja generowana w sposób ciągły z kodu, regenerowana przy każdej istotnej zmianie kodu. Dokumentacja jest zawsze aktualna, ponieważ zawsze pochodzi z aktualnego stanu kodu. To model żywej dokumentacji, a nie diagramy, które ktoś aktualizuje, gdy o tym pamięta, lecz diagramy regenerowane z kodu za każdym razem, gdy ten ulega zmianie.
Praktyczna różnica w przypadku starszego portfolio COBOL: statyczne podejście do pochodzenia generuje diagram zależności na podstawie bieżącej analizy źródłowej COBOL i oznacza go znacznikiem czasu. Co tydzień analiza może być ponownie uruchamiana, a nowy diagram porównywany z poprzednim. Zmiany są widoczne jako różnice między kolejnymi wynikami analizy. Dynamiczne podejście do pochodzenia integruje analizę z procesem zarządzania zmianami w systemie mainframe, generując zaktualizowany diagram za każdym razem, gdy program jest wdrażany do produkcji.
Diagramy jako kod: co działa, a czego brakuje
Współczesną odpowiedzią na przestarzałe diagramy statyczne są diagramy jako kod, czyli dokumentacja architektoniczna w formacie tekstowym, który można kontrolować pod kątem wersji, różnicować, recenzować i generować programowo. Głównymi narzędziami są Mermaid, PlantUML i model C4 w formie kodu.
For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB
Ten diagram syreny znajduje się w repozytorium, wraz z kodem, który przedstawia. Kiedy programista dodaje nową usługę, aktualizuje ten plik w tym samym żądaniu ściągnięcia. Przegląd kodu obejmuje zmianę diagramu. Dokumentacja i kod są przesyłane razem.
Czego diagramy jako kod nie rozwiązują:
Nie rozwiązuje to problemu z dokumentacją starszych systemów. Program COBOL dodany do biblioteki mainframe przez programistę, który przesyła polecenie kompilacji JCL zamiast żądania ściągnięcia z Gita, nie powoduje aktualizacji pliku Mermaid. Proces zarządzania zmianami w mainframe i proces dokumentacji oparty na Gicie to oddzielne systemy bez automatycznej synchronizacji.
Nie rozwiązuje to problemu nadmiernej precyzji. Diagram syreny, który trzeba ręcznie aktualizować dla każdej nowej usługi, nadal wymaga ludzkiej dyscypliny, którą proces ten miał zastąpić. Jeśli aktualizacja diagramu jest krokiem ręcznym, zostanie pominięta.
Nie naprawia wstecznie starszych diagramów. W przypadku portfolio COBOL bez istniejącej dokumentacji nadającej się do odczytu maszynowego, diagramy jako kod zapewniają ramy dla przyszłej dokumentacji, ale nie generują bieżącej dokumentacji.
Podejście do analizy strukturalnej systemów starszych
W przypadku starszych systemów, w których diagramy jako kod są niepraktyczne, ponieważ przepływ pracy programistycznej nie przechodzi przez Git, istniejąca dokumentacja jest zbyt nieaktualna, aby stanowić punkt wyjścia dla podejścia opartego na tekście lub baza kodu nigdy nie została formalnie udokumentowana, strukturalna analiza kodu jest jedynym mechanizmem, który pozwala na generowanie aktualnej, dokładnej dokumentacji od podstaw.
Analiza strukturalna analizuje rzeczywisty kod, programy COBOL, strumienie zadań JCL, copybooki, osadzony kod SQL i wyprowadza relacje zależności, inwentaryzacje programów i struktury danych bezpośrednio z zawartości kodu. Wynikiem nie jest diagram narysowany przez człowieka, który zrozumiał kod; jest to diagram algorytmicznie wyprowadzony z samego kodu. Jego dokładność jest ograniczona dokładnością analizy, a nie pamięcią programisty, który go narysował.
Przepływ pracy:
bash
# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/
# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
--format mermaid \
--output /docs/dependency-graph.md
# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
--format markdown \
--output /docs/program-inventory.md
# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
--baseline /docs/analysis/2026-09-01/ \
--current /docs/analysis/2026-10-01/ \
--output /docs/changes/delta-report.md
Raport delta, czyli różnica między dwiema kolejnymi analizami, to rejestr zmian generowany automatycznie przez statyczne pochodzenie diagramu. Dodane i usunięte programy, zmienione zależności, zmodyfikowane kopie zapasowe: wszystkie te dane pojawiają się w raporcie delta bez konieczności ręcznego dokumentowania.
Diagram wygenerowany przez ostatnią analizę to dokumentacja aktualna na dzień analizy. Uruchamianie analizy według harmonogramu, co tydzień lub przy każdym awansie produkcyjnym, generuje dokumentację aktualizowaną w zdefiniowanym tempie, bez konieczności ciągłego, ręcznego tworzenia dokumentacji.
Ramy zapobiegania dokumentacji
Aby zapobiegać zadłużeniu dokumentacyjnemu, należy zająć się pięcioma mechanizmami nieaktualności za pomocą konkretnych, możliwych do wdrożenia praktyk:
W obliczu problemu akumulacji delty:
- Ustal rytm analizy: cotygodniowy dla systemów o dużej prędkości, miesięczny dla systemów stabilnych
- Generuj dokumentację z kodu przy każdym uruchomieniu analizy, a nie ręcznie
- Utwórz raport delta dla każdego przebiegu, pokazujący zmiany od ostatniej analizy
W odpowiedzi na problem brakującego pochodzenia:
- Każdy diagram zawiera źródło generacji (datę i wersję analizy kodu)
- Nigdy nie publikuj diagramu bez odnotowania, w jaki sposób i kiedy został on utworzony
- Przechowuj wygenerowane diagramy wraz z wynikami analiz, które je wygenerowały
Przeciwko problemowi dryfu własnościowego:
- Generowanie dokumentacji to etap procesu, a nie indywidualna odpowiedzialność
- Rurociąg jest właścicielem dokumentacji, odejście żadnej osoby jej nie narusza
- Wygenerowana dokumentacja nie ma właściciela, od którego można się oddalić
Przeciwko problemowi nadmiernej precyzji:
- Przed utworzeniem każdego typu diagramu zdefiniuj odpowiedni poziom abstrakcji
- Diagramy inwentaryzacji komponentów na poziomie usługi/programu, a nie funkcji
- Diagramy relacji na poziomie granic domeny, a nie na poziomie pojedynczego połączenia
- Generowane są szczegółowe diagramy (wykresy połączeń, schematy danych), a nie rysowane ręcznie
Przeciwdziałanie problemowi blokady formatu:
- Wygenerowane diagramy w formatach tekstowych (Mermaid, GraphViz DOT, SVG)
- Brak dokumentacji architektonicznej w formacie Visio, PowerPoint lub PDF
- Źródła diagramów przechowywane w systemie kontroli wersji wraz z kodem, który dokumentują
W jaki sposób SMART TS XL Rozwiązuje problem długu związanego z dokumentacją archiwalną
W przypadku starszych portfeli COBOL i komputerów mainframe SMART TS XL jest silnikiem analizy strukturalnej, który umożliwia tworzenie dokumentacji opartej na dowodach i sprawia, że „regeneracja z kodu” staje się praktyczną alternatywą dla „aktualizacji diagramu programu SharePoint 2009”.
Funkcja statycznej analizy kodu analizuje każdy program COBOL, copybook, strumień zadań JCL i osadzone polecenie SQL, aby wygenerować inwentarz programów, metryki złożoności i identyfikację martwego kodu, które stanowią podstawę każdej dokładnej dokumentacji legacy. Ten inwentarz to oparty na dowodach zamiennik ręcznie prowadzonej listy programów, która jest zawsze niekompletna, zawsze nieaktualna i zawsze błędna w sposób, o którym nikt nie wie.
Mapowanie zależności aplikacji generuje graf zależności, każdą relację CALL, każdą relację COPY i każdy przepływ danych między programami, który stanowi rdzeń dokumentacji architektury. Ten graf jest generowany na podstawie kodu przy każdym uruchomieniu analizy, tworząc diagram zależności aktualny na dzień ostatniej analizy, bez konieczności ręcznej dokumentacji między uruchomieniami.
Funkcja analizy wpływu generuje dokumentację delta: po wprowadzeniu zmiany w bazie kodu, analiza wpływu identyfikuje wszystkie zmiany w stosunku do stanu poprzedniego. Jest to zautomatyzowany raport delta, który rozwiązuje narastający problem delta. Każda zmiana, która pogłębiłaby rozbieżność między diagramem a rzeczywistością, jest automatycznie rejestrowana i dokumentowana.
Funkcja wyszukiwania korporacyjnego umożliwia wyszukiwanie w dokumentacji: znajdź każdy program wywołujący określony podprogram (fragment grafu wywołań komponentu), każdy program zawierający określony copybook (zakres zależności współdzielonego komponentu), każdy program zmodyfikowany po określonej dacie (dziennik zmian dla określonego okresu). Ta funkcja wyszukiwania to interfejs dokumentacji, narzędzie, które odpowiada na pytania dotyczące bieżącego stanu systemu na podstawie bieżącej analizy, a nie statycznego diagramu, który może być nieaktualny od lat.
Dla organizacji prowadzących modernizacja dziedziczna programy SMART TS XLGenerowanie dokumentacji jest krokiem wstępnym: diagram zależności, inwentaryzacja programu i dokumentacja schematu danych, których program modernizacji potrzebuje do zdefiniowania zakresu, sekwencji fal migracji i walidacji wyników. Ta dokumentacja nie może pochodzić z archiwum programu SharePoint. Musi pochodzić z kodu.
Jedyny dokładny diagram to ten, który pochodzi z kodu
Diagram architektury z 2009 roku na stronie programu SharePoint będzie nadal dostępny, dopóki ktoś go jawnie nie usunie. Będzie on nadal wysyłany nowym programistom, gdy będą pytać o działanie systemu. Będzie on nadal służył do podejmowania decyzji dotyczących systemu, którego już nie opisuje dokładnie. Różnica między diagramem a systemem będzie się pogłębiać z każdym zatwierdzeniem, wdrożeniem, dodaniem i wycofaniem programu.
Alternatywą nie jest „częstsze aktualizowanie diagramów”. Procesy wymagające od człowieka dyscypliny w celu utrzymania kodu, który ciągle się zmienia, mają znany tryb awarii: dyscyplina zawodzi. Alternatywą jest dokumentacja generowana z kodu, wykorzystująca go jako źródło prawdy, regenerująca się automatycznie po zmianie kodu i zawierająca znacznik czasu analizy, który dokładnie informuje każdego czytelnika o jej aktualności.
W przypadku nowoczesnych systemów chmurowych, diagramy jako kod i narzędzia do tworzenia żywej dokumentacji zapewniają to rozwiązanie. W przypadku starszych systemów COBOL, zapewnia je strukturalna analiza kodu. Mechanizm jest inny, ale zasada jest ta sama: diagram jest dokładny, gdy jest generowany z kodu, i akumuluje dług od momentu oddzielenia go od kodu, który go wygenerował.
Jedynym diagramem, który pozostaje aktualny, jest diagram narysowany przez kod.


