דיאגרמת הארכיטקטורה בדף SharePoint נוצרה בשנת 2009. היא הייתה מדויקת אז, היא שיקפה את המערכת כפי שהייתה קיימת בזמן הגירת פלטפורמה משמעותית, שצוירה על ידי ארכיטקט שבילה שלושה שבועות בתיעוד כל רכיב והקשרים בינו לבין המערכת. מאז 2009, המערכת קיבלה כ-4,800 קומיטים, חמישה עשר צוותים תרמו לה, ארבעה מהרכיבים המוצגים בדיאגרמה אינם קיימים עוד, אחד עשר רכיבים חדשים נוספו ומעולם לא תוכננו, והארכיטקט שצייר אותה פרש בשנת 2016. הדיאגרמה עדיין קיימת. כאשר מפתח חדש מצטרף ושואל "איך המערכת עובדת?", מישהו שולח לו את הקישור ל-SharePoint. הדיאגרמה אינה תיעוד. זוהי ארכיאולוגיה.
חוב תיעוד הוא חוב טכני המוחל על שכבת התיעוד: הפער המצטבר בין מה שהתיעוד אומר על מערכת לבין מה שהמערכת עושה בפועל. סחף אדריכלי, שבו דיאגרמות מתנתקות מהמערכות שהן מתארות, הוא גם הצורה הנפוצה ביותר וגם המסוכנת ביותר של חוב תיעוד. זהו המסוכן ביותר משום שהוא מציג ביטחון כוזב: דיאגרמה שקיימת ונראית מקצועית נותנת לבעלי העניין את הרושם שהמערכת מובנת, כשלמעשה מה שהם רואים הוא ממצא היסטורי המתאר מערכת שכבר אינה קיימת בצורה המוצגת. דיאגרמות מיושנות גרועות יותר מהיעדר דיאגרמות משום שחוסר דיאגרמות מניע אנשים לגלות מה באמת קיים שם; דיאגרמות מיושנות מניע אנשים לפעול על סמך מה שכבר אינו נכון.
תיעוד ללא מאמץ
SMART TS XL מייצר יומן שינויים של כל שינוי בתוכנית, תלויות וספר עותקים מאז הרצת הניתוח הקודמת.
גלו עוד…חמשת המנגנונים שגורמים לדיאגרמות להתיישן
כל מאמר על סחף תיעוד אומר ש"דיאגרמות מתיישנות עם הזמן". כמעט אף אחד מהם לא מסביר את המנגנונים הספציפיים שדרכם זה קורה. הבנת המנגנונים היא תנאי הכרחי למניעתם, מכיוון שמנגנונים שונים דורשים אסטרטגיות מניעה שונות.
1. בעיית הדלתא המצטברת. דיאגרמה היא תמונת מצב של מערכת בנקודת זמן. כל שינוי קוד לאחר תמונת מצב זו הוא דלתא בין הדיאגרמה למציאות. דלתות בודדות הן בדרך כלל קטנות, שירות חדש, רכיב ששמו שונה, תלות שנוספה. קל לתעד כל אחת מהן בנפרד. הבעיה היא שאף אחד לא מתעד אותן בהדרגה, מכיוון שעדכון הדיאגרמה עבור כל שינוי נתפס כתקורה ללא תועלת מיידית. לאחר 100 דלתות שלא תועדו, הדיאגרמה שגויה באופן מהותי. לאחר 1,000, היא בדיונית באופן מהותי.
2. בעיית המקור החסר. דיאגרמה שאין לה קישור תכנותי לקוד שהיא מתארת אינה מכילה מנגנון לגילוי מתי היא הופכת לא מדויקת. אין אות שמופעל כאשר שינוי בבסיס הקוד סותר טענה בדיאגרמה. הדיאגרמה והקוד הם ארטיפקטים מנותקים שמתארים במקרה את אותה מערכת, אך הקשר קיים רק בתודעתם של האנשים שציירו את הדיאגרמה, ורק כל עוד אותם אנשים זוכרים אותה.
3. בעיית סחף הבעלות. דיאגרמות ארכיטקטורה נוצרות בדרך כלל על ידי אדם ספציפי ברגע מסוים. כאשר אותו אדם עוזב, הידיעה השקטה שהפכה את הדיאגרמה למדויקת, ההבנה של אילו רכיבים הושמטו במכוון, אילו קשרים פושטו, אילו תוויות היו קיצור למשהו מורכב יותר, עוזבת איתו. האפוטרופוס החדש של הדיאגרמה יורש ארטיפקט שהוא לא יצר, אולי לא מבין במלואו, ואין לו תמריץ לתחזק אותו מול בסיס קוד שהוא לא תכנן.
4. בעיית דעיכת הדיוק יתר על המידה. דיאגרמות המציגות יותר מדי פרטים הופכות מתיישנות מהר יותר מדיאגרמות המציגות הפשטה מתאימה. דיאגרמה המציגה כל מיקרו-שירות, כל נקודת קצה של API וכל טבלת מסד נתונים צריכה להתעדכן עבור כל פריסה. דיאגרמה המציגה תחומי שירות ודפוסי האינטראקציה העיקריים שלהם צריכה להתעדכן רק כאשר גבולות התחומים משתנים. לדיאגרמות מדויקות יתר על המידה יש זמן מחצית חיים של קיפאון הנמדד בספרינטים; לדיאגרמות מופשטות כראוי יש זמן מחצית חיים של קיפאון הנמדד ברבעונים.
5. בעיית נעילת הפורמט. דיאגרמות המאוחסנות כקבצי Visio, שקופיות PowerPoint, ייצוא PNG או קבצי PDF מצורפים לא ניתנות ליצירה, אימות או השוואה תכנותית. אין דרך לשאול "האם דיאגרמה זו עדיין תואמת את הקוד?" מכיוון שהדיאגרמה היא תמונת פיקסל והקוד הוא טקסט. בחירת הפורמט שנעשית בעת יצירת הדיאגרמה קובעת האם ניתן אי פעם לאמת את הדיאגרמה מול המערכת שהיא מתארת.
אסון התיעוד של מערכת מדור קודם
עבור מערכות מודרניות מבוססות ענן עם צוותי פיתוח פעילים, דיאגרמות תקינות הן בעיית ניהול, הנפתרת באמצעות שיטות של ארכיטקטורה כקוד, כלי תיעוד חי ומשמעת הנדסית. המערכת משתנה לעתים קרובות; ניתן לעדכן את הדיאגרמה כדי להתאים אותה אם התהליך נכון.
עבור מערכות מדור קודם, הבעיה שונה בסוגה, לא רק בדרגתה.
דיאגרמת ארכיטקטורה שצוירה במהלך סקירת תכנון מערכת מיינפריים בשנת 1992 עשויה לצבור 30 שנות שינויי קוד מאז יצירתה. כל שנה של תחזוקה פעילה על תיק COBOL מורכב מייצרת מאות קומיטים, תוכניות חדשות שנוספו, תוכניות ישנות הוצאו משימוש, ספרי עותקים עודכנו, וזרמי משימות JCL אורגנו מחדש. הדיאגרמה משנת 1992 הייתה מדויקת אז. מאז היא הולכת ופוחתת מדי שנה. עד 2026, הפער בין הדיאגרמה למערכת עשוי להיות גדול יותר מהמערכת המקורית עצמה, קיימות יותר תוכניות חדשות שאינן בדיאגרמה מאשר תוכניות מהמערכת המקורית שעדיין פועלות כפי שתוכנן במקור.
מה שהופך את זה לאסון ולא סתם לא נוח הוא אופן השימוש בתרשים. כאשר צוות מודרניזציה מגיע להעריך את המערכת, הם לא יודעים שהתרשים שגוי. אין להם דרך לדעת עד כמה הוא שגוי. התרשים נראה מקצועי. יש בו תיבות רכיבים, חיצי קשר, הערות. זה מרמז שמישהו הבין את המערכת הזו מספיק טוב כדי לצייר אותה. הצוות משתמש בה כנקודת מוצא, וכל ניתוח שנבנה על נקודת מוצא שגויה מייצר מסקנות שגויות.
מסגרת הביקורת של Docuwriter מנסחת זאת בבירור: ביקורת תיעוד ראויה "הופכת אי נוחות מעורפלת לעובדות הניתנות לבדיקה". עבור מערכות מדור קודם, ביקורת התיעוד כמעט תמיד מניבה את אותה הממצא: הדיאגרמות נעדרות או ישנות כל כך שהן מייצגות מערכת שלא קיימת כבר שנים. העובדות הניתנות לבדיקה, כאשר הן נחשפות סוף סוף, מתארות מערכת שונה באופן מהותי ממה שממנה עבדו.
מצב הכשל הספציפי: צוות מודרניזציה מעריך את היקף ההגירה מהדיאגרמה משנת 1992. היא מציגה 180 רכיבים. הניתוח המבני של בסיס הקוד בפועל מגלה 340 תוכניות, 80 מהן קוד מת ועוד 40 מהן נוספו לאחר 1992 ומעולם לא שורטטו. הערכת ההיקף הייתה שגויה פי שניים לפני שנכתבה השורה הראשונה של הקוד החדש.
קטגוריות דיאגרמה לפי שיעור יישנות
לא כל הדיאגרמות הופכות לבלתי צפויות באותו קצב. קצב הבלתי צפויות תלוי במה שהדיאגרמה מתארת, באיזו תדירות משתנים האלמנטים המתוארים, ובאיזו מידה בדיוק הדיאגרמה מייצגת את האלמנטים הללו.
| סוג דיאגרמה | מה משתנה לעתים קרובות | שיעור קיפאון | עדיפות להפחתת השפעות |
|---|---|---|---|
| מלאי שירותים/רכיבים | שירותים חדשים נוספו, שירותים ישנים הוצאו משימוש | גָבוֹהַ | קריטי - תדירות השינויים הגבוהה ביותר |
| מפת תלות/אינטגרציה | ממשקי API נוספו, אינטגרציות שונו, זרימות נתונים שונו | גָבוֹהַ | קריטי - כל פריסה יכולה לשנות זאת |
| מודל נתונים / ERD | שינויי סכימה, טבלאות חדשות, שינויי עמודות | בינוני גבוה | גבוה - שינויי סכמה מתרחשים תכופים בפיתוח פעיל |
| דיאגרמות רצף | שינויים בלוגיקה עסקית, עדכוני חוזי API | בינוני | גבוה - כל שינוי בתהליך העבודה מבטל את אלה |
| תשתית / פריסה | אינפרא-אס-קוד מניע שינויים תכופים | גָבוֹהַ | בינוני - כלי IaC יכולים לייצר אותם באופן אוטומטי |
| תחום / הקשר מוגבל | שינויים ארגוניים ובעלות | נמוך-בינוני | נמוך - גבולות הדומיין משתנים רבעוני או פחות |
| רישומי החלטות (ADRs) | משתנה לעיתים רחוקות (החלטות הן היסטוריות) | מאוד נמוך | נמוך - לאחר רישום נכון, נשאר מדויק |
| גרף קריאת תוכנית (COBOL) | כל שינוי קוד עלול לשנות זאת | גבוה מאוד | קריטי למורשת - שינויים בלתי נראים |
| מחברת / סכימה (COBOL) | כל שינוי ב-FD משפיע על מספר תוכניות | גָבוֹהַ | קריטי לדור הקודם - שינויים מתגלגלים בשקט |
שתי השורות התחתונות הן ערכים ספציפיים לתוכנית מדור קודם שאף הנחיה תיעודית סטנדרטית אינה מטפלת בהם. גרף קריאה של תוכנית COBOL עלול להפוך לפסול על ידי כל שינוי קוד בכל תוכנית בעץ הקריאה. ספר עותקים המשותף ל-200 תוכניות הופך לפסול עבור כל תוכנית כאשר ספר העותקים משתנה. לדיאגרמות אלו יש את שיעור היעדר התקדמות הגבוה ביותר בכל תיק עבודות ארגוני ואת ההשלכות החמורות ביותר כאשר הן יעושנות, מכיוון שהתוכניות שהן מתארות הן אלו שמפעילות את תהליכי העסק הקריטיים ביותר.
פתרון המקור: מעקב אחר דיאגרמות עד למקורן
שורש חוב התיעוד אינו היעדר תהליך עדכון תיעוד. זהו היעדר מקור, הקישור הניתן למעקב מאלמנט דיאגרמה לארטיפקט הקוד שהוא מתאר. ללא מקור, אין מנגנון לגילוי חוסר תקינות. עם מקור, זיהוי חוסר תקינות הוא אוטומטי: אם ארטיפקט הקוד השתנה מאז שהדיאגרמה נוצרה, הדיאגרמה מיושנת.
מקור בתיעוד קיים בשתי רמות:
מקור סטטי הוא תיעוד שנוצר מקוד בנקודת זמן, עם חותמת זמן של יצירה והפניה למצב הקוד (hash של commit, גרסה, תאריך ניתוח) שהתיעוד משקף. מקור סטטי אינו מונע קיפאון, אך הוא מאפשר זיהוי קיפאון: חותמת הזמן מראה שהתיעוד נוצר מ-commit. abc123 בתאריך מסוים, וה-commit הנוכחי הוא def456 במועד מאוחר יותר. הפער בין שני הקומיטים הוא הפער בין התיעוד לקוד הנוכחי.
מקור דינמי הוא תיעוד שנוצר באופן רציף מהקוד, ומתחדש בכל שינוי קוד רלוונטי. התיעוד תמיד עדכני משום שהוא תמיד נגזר ממצב הקוד הנוכחי. זהו מודל התיעוד החי, לא דיאגרמות שמישהו מעדכן כשהוא זוכר לעשות זאת, אלא דיאגרמות שנוצרות מחדש מהקוד בכל פעם שהקוד משתנה.
ההבדל המעשי עבור תיק COBOL מדור קודם: גישת מקור סטטית מייצרת את דיאגרמת התלות מניתוח מקור COBOL הנוכחי ומוסיפה לה חותמת זמן. בכל שבוע, ניתן להריץ מחדש את הניתוח ולהשוות את הדיאגרמה החדשה לקודמתה. שינויים גלויים כהבדלים בין פלטי ניתוח עוקבים. גישת מקור דינמית משלבת את הניתוח בצינור ניהול השינויים של המחשב המרכזי, ויוצרת דיאגרמה מעודכנת בכל פעם שתוכנית מקודמת למצב ייצור.
דיאגרמות כקוד: מה עובד ומה חסר
התגובה המודרנית לדיאגרמות סטטיות מיושנות היא דיאגרמות-כקוד, המבטאות תיעוד אדריכלי בפורמט טקסט שניתן לשלוט בגירסאות, לשנות, לסקור וליצור באופן תכנותי. Mermaid, PlantUML ומודל C4 בצורת קוד הם הכלים העיקריים.
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
דיאגרמת בת הים הזו נמצאת במאגר, לצד הקוד שהיא מתארת. כאשר מפתח מוסיף שירות חדש, הוא מעדכן קובץ זה באותה בקשת משיכה. סקירת הקוד כוללת את שינוי הדיאגרמה. התיעוד והקוד עוברים יחד.
מה שדיאגרמות כקוד לא פותרות:
זה לא פותר תיעוד של מערכות מדור קודם. תוכנית COBOL שנוספה לספריית מיינפריים על ידי מפתח ששולח בקשת קומפילציה של JCL במקום בקשת משיכה של Git אינה מפעילה עדכון קובץ Mermaid. תהליך ניהול השינויים במיינפריים ותהליך התיעוד מבוסס Git הן מערכות נפרדות ללא סנכרון אוטומטי.
זה לא פותר את בעיית הדיוק היתר. דיאגרמת בת ים שחייבת להתעדכן ידנית עבור כל שירות חדש עדיין דורשת את המשמעת האנושית שהתהליך היה אמור להחליף. אם עדכון הדיאגרמה הוא שלב ידני, הוא ידלג.
זה לא מתקן רטרואקטיבית דיאגרמות מדור קודם. עבור תיק עבודות COBOL ללא תיעוד קריא על ידי מכונה קיים, דיאגרמות כקוד מספקות מסגרת לתיעוד עתידי אך אינן מייצרות את התיעוד הנוכחי.
גישת הניתוח המבני עבור מערכות מדור קודם
עבור מערכות מדור קודם שבהן דיאגרמות-כקוד אינן מעשיות, מכיוון שזרימת העבודה של הפיתוח אינה עוברת דרך Git, מכיוון שהתיעוד הקיים מיושן מדי מכדי לשמש כנקודת התחלה לגישה מבוססת טקסט, או מכיוון שבסיס הקוד מעולם לא תועד רשמית, ניתוח קוד מבני הוא המנגנון היחיד שמייצר תיעוד עדכני ומדויק מנקודת התחלה.
ניתוח מבני מנתח את הקוד בפועל, תוכניות COBOL, זרמי משימות JCL, ספרי עותקים, SQL מוטמע, וגוזר את יחסי התלות, מלאי התוכניות ומבני הנתונים ישירות ממה שהקוד מכיל. הפלט אינו דיאגרמה שצוירה על ידי אדם שהבין את הקוד; זוהי דיאגרמה הנגזרת באופן אלגוריתמי מהקוד עצמו. דיוקה מוגבל בדיוק הניתוח, ולא בזיכרון של המפתח שצייר אותה.
תהליך העבודה:
לחבוט
# 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
דוח הדלתא, ההבדל בין שני ניתוחים עוקבים, הוא יומן השינויים שמקורו הסטטי של הדיאגרמה מייצר באופן אוטומטי. תוכניות שנוספו, תוכניות שהוסרו, תלויות שונו, ספרי עותקים שונו: כולם מופיעים בדוח הדלתא ללא כל מאמץ תיעוד אנושי.
הדיאגרמה שנוצרת על ידי הניתוח האחרון היא התיעוד העדכני נכון לתאריך הניתוח. הרצת הניתוח על פי לוח זמנים, שבועי או מופעל על ידי כל קידום ייצור, מייצרת תיעוד עדכני בקצב מוגדר ללא כל מאמץ תיעוד ידני מתמשך.
מסגרת מניעת התיעוד
מניעת חוב תיעוד דורשת התייחסות לחמשת מנגנוני הקיפאון באמצעות שיטות עבודה ספציפיות וניתנות ליישום:
כנגד בעיית הדלתא המצטברת:
- קבעו קצב ניתוח: שבועי עבור מערכות במהירות גבוהה, חודשי עבור מערכות יציבות.
- צור תיעוד מקוד בכל הרצת ניתוח, לא באופן ידני
- הפק דוח דלתא על כל ריצה המציג מה השתנה מאז הניתוח האחרון
כנגד בעיית המקור החסר:
- כל דיאגרמה כוללת את מקור היצירה שלה (תאריך ניתוח הקוד וגרסה)
- לעולם אל תפרסמו דיאגרמה מבלי לתעד כיצד ומתי היא נוצרה
- אחסן דיאגרמות שנוצרו לצד פלטי הניתוח שיצרו אותן
נגד בעיית סחף הבעלות:
- יצירת תיעוד היא שלב בצנרת, לא אחריות אישית
- הצינור הוא הבעלים של התיעוד; אף עזיבה של אדם לא מפרה אותו
- לתיעוד שנוצר אין בעלים ממנו ניתן להתרחק
נגד בעיית הדיוק היתר:
- הגדר את רמת ההפשטה המתאימה לכל סוג דיאגרמה לפני יצירתה
- דיאגרמות מלאי רכיבים ברמת השירות/תוכנית, לא ברמת הפונקציה
- דיאגרמות קשר ברמת גבול התחום, לא ברמת הקריאה הבודדת
- דיאגרמות מפורטות (גרפי שיחות, סכמות נתונים) נוצרות, לא מצוירות ידנית.
נגד בעיית נעילת הפורמט:
- דיאגרמות שנוצרו בפורמטים מבוססי טקסט (Mermaid, GraphViz DOT, SVG)
- אין תיעוד ארכיטקטורה ב-Visio, PowerPoint או PDF בלבד
- מקורות דיאגרמה המאוחסנים בבקרת גרסאות לצד הקוד שהם מתעדים
איך SMART TS XL מטפל בחובות תיעוד מדור קודם
עבור תיקי COBOL ומיינפריים מדור קודם, SMART TS XL הוא מנוע הניתוח המבני שמאפשר תיעוד מבוסס ראיות, ושהופך את "יצירה מחדש מהקוד" לחלופה מעשית ל"עדכון דיאגרמת SharePoint 2009".
יכולת ניתוח הקוד הסטטי מנתחת כל תוכנית COBOL, ספר עותקים, זרם משימות JCL ומשפט SQL מוטמע כדי לייצר את רשימת התוכניות, מדדי המורכבות וזיהוי הקוד המת המהווים את שכבת הבסיס של כל תיעוד מדויק מדור קודם. רשימת תוכניות זו היא התחליף המבוסס על ראיות לרשימת התוכניות המתוחזקת ידנית, שתמיד אינה שלמה, תמיד לא מעודכנת ותמיד שגויה בדרכים שאף אחד לא מכיר.
מיפוי תלות האפליקציה מייצר את גרף התלות, כל קשר CALL, כל קשר COPY, כל זרימת נתונים בין תוכניות, שהוא הליבה של תיעוד הארכיטקטורה. גרף זה נוצר מחדש מהקוד בכל הרצת ניתוח, ויוצר דיאגרמת תלות עדכנית נכון לניתוח האחרון ללא כל מאמץ תיעוד אנושי בין הרצות.
יכולת ניתוח ההשפעה מייצרת את תיעוד הדלתא: כאשר מתבצע שינוי בבסיס הקוד, ניתוח ההשפעה מזהה את כל מה שהשתנה יחסית למצב הקודם. זהו דוח הדלתא האוטומטי המטפל בבעיית הדלתא המצטברת, כל שינוי שהיה מרחיב את הפער בין דיאגרמה למציאות נקלט ומתועד באופן אוטומטי.
יכולת החיפוש הארגוני הופכת את התיעוד לניתן לשאילתה: מצא כל תוכנית שקוראת לתת-תוכנית ספציפית (קטע גרף הקריאה עבור רכיב), כל תוכנית הכוללת ספר עותקים ספציפי (היקף התלות של רכיב משותף), כל תוכנית ששונתה לאחר תאריך מסוים (יומן השינויים עבור תקופת זמן). יכולת חיפוש זו היא ממשק התיעוד, הכלי שעונה על שאלות לגבי מצב המערכת הנוכחי מהניתוח הנוכחי, ולא מדיאגרמה סטטית שעשויה להיות מיושנת לפני שנים.
עבור ארגונים המבצעים מודרניזציה מורשת תוכניות, SMART TS XLיצירת התיעוד של היא השלב הנדרש: דיאגרמת התלות, מלאי התוכניות ותיעוד סכמת הנתונים שתוכנית המודרניזציה זקוקה להם כדי להגדיר את ההיקף, לרצף גלי הגירה ולאמת תוצאות. תיעוד זה אינו יכול להגיע מארכיון SharePoint. עליו להגיע מהקוד.
הדיאגרמה המדויקת היחידה היא זו שנגזרת מהקוד
דיאגרמת הארכיטקטורה של 2009 בדף SharePoint תמשיך להתקיים עד שמישהו ימחק אותה במפורש. היא תמשיך להישלח למפתחים חדשים כאשר הם ישאלו כיצד המערכת פועלת. היא תמשיך לשמש כבסיס להחלטות לגבי מערכת שהיא כבר לא מתארת במדויק. הפער בין הדיאגרמה למערכת ימשיך להתרחב עם כל commit, כל פריסה, כל הוספה ויציאה משימוש של תוכנית.
האלטרנטיבה אינה "לעדכן את הדיאגרמות לעתים קרובות יותר". תהליכים הדורשים משמעת אנושית כדי לתחזק אותם מול קוד שמשתנה ללא הרף, ידועים כמצב כשל: המשמעת נכשלת. האלטרנטיבה היא תיעוד הנגזר מהקוד, המשתמש בקוד כמקור האמת שלו, שנוצר מחדש אוטומטית כאשר הקוד משתנה, ונושא את חותמת הזמן של הניתוח שאומרת לכל קורא בדיוק עד כמה הוא עדכני.
עבור מערכות ענן מודרניות, דיאגרמות כקוד וכלי תיעוד חי מספקים זאת. עבור מערכות COBOL מדור קודם, ניתוח קוד מבני מספק זאת. המנגנון שונה; העיקרון זהה: הדיאגרמה מדויקת כאשר היא נגזרת מהקוד, והיא צוברת חוב מרגע שהיא מופרדת מהקוד שיצר אותה.
הדיאגרמה היחידה שנשארת עדכנית היא הדיאגרמה שצוירה על ידי הקוד.


