כיצד הערכנו את איכות התיעוד

שלום, הבר! שמי לשה, אני מנתח מערכות באחד מצוותי המוצר של אלפא-בנק. כעת אני מפתח בנק מקוון חדש עבור ישויות משפטיות ויזמים בודדים.

וכשאתה אנליסט, במיוחד בערוץ כזה, אתה לא יכול להגיע לשום מקום בלי תיעוד ועבודה צמודה איתו. ותיעוד זה משהו שתמיד מעלה הרבה שאלות. מדוע יישום האינטרנט אינו מתואר? למה המפרט מציין איך השירות צריך לעבוד, אבל זה לא עובד ככה בכלל? מדוע רק שני אנשים, אחד מהם כתב אותו, יכולים להבין את המפרט?

עם זאת, לא ניתן להתעלם מהתיעוד מסיבות ברורות. וכדי להקל על חיינו, החלטנו להעריך את איכות התיעוד. איך בדיוק עשינו את זה ולאילו מסקנות הגענו נמצא מתחת לגזרה.

איכות התיעוד

כדי לא לחזור על "בנק אינטרנט חדש" כמה עשרות פעמים בטקסט, אכתוב NIB. כעת יש לנו יותר מתריסר צוותים שעובדים על פיתוח NIB עבור יזמים וישויות משפטיות. יתרה מכך, כל אחד מהם יוצר תיעוד משלו עבור שירות חדש או יישום אינטרנט מאפס, או מבצע שינויים בקיים. האם בגישה זו התיעוד באופן עקרוני יכול להיות איכותי?

וכדי לקבוע את איכות התיעוד, זיהינו שלושה מאפיינים עיקריים.

1. זה חייב להיות שלם. זה נשמע די קפטן, אבל חשוב לציין. זה צריך לתאר בפירוט את כל המרכיבים של הפתרון המיושם.
2. זה חייב להיות רלוונטי. כלומר, מתאימים ליישום הנוכחי של הפתרון עצמו.
3. זה צריך להיות מובן. כך שהאדם המשתמש בו יבין בדיוק כיצד הפתרון מיושם.

לסיכום - תיעוד מלא, עדכני ומובן.

ראיון

כדי להעריך את איכות התיעוד, החלטנו לראיין את מי שעובדים איתו ישירות: אנליסטים של NIB. המשיבים התבקשו להעריך 10 הצהרות לפי הסכמה "בסולם מ-1 עד 5 (לא מסכים לחלוטין - מסכים לחלוטין)."

ההצהרות שיקפו את מאפייני התיעוד האיכותי ואת חוות הדעת של מרכיבי הסקרים לגבי מסמכי NIB.

1. התיעוד עבור יישומי NIB מעודכן ותואם באופן מלא ליישום שלהם.
2. היישום של יישומי NIB מתועד במלואו.
3. יש צורך בתיעוד עבור יישומי NIB רק לתמיכה פונקציונלית.
4. תיעוד עבור יישומי NIB עדכני בזמן הגשתם לתמיכה פונקציונלית.
5. מפתחי יישומי NIB משתמשים בתיעוד כדי להבין מה הם צריכים ליישם.
6. יש מספיק תיעוד עבור יישומי NIB כדי להבין כיצד הם מיושמים.
7. אני מעדכן מיד תיעוד על פרויקטים של NIB אם הם מסתיימים (על ידי הצוות שלי).
8. מפתחי יישומי NIB בודקים תיעוד.
9. יש לי הבנה ברורה כיצד להכין תיעוד לפרויקטים של NIB.
10. אני מבין מתי לכתוב/לעדכן תיעוד עבור פרויקטים של NIB.

ברור שפשוט מענה "מ-1 עד 5" עלול לא לחשוף את הפרטים הדרושים, כך שאדם יכול להשאיר תגובה על כל פריט.

עשינו את כל זה באמצעות Slack הארגוני - פשוט שלחנו הזמנה למנתחי מערכות להשתתף בסקר. היו 15 אנליסטים (9 ממוסקבה ו-6 מסנט פטרסבורג). לאחר השלמת הסקר, הפקנו ציון ממוצע עבור כל אחת מ-10 ההיגדים, שאותו תיקננו לאחר מכן.

הנה מה שקרה.

הסקר הראה שלמרות שאנליסטים נוטים להאמין שהיישום של יישומי NIB מתועד במלואו, הם אינם נותנים הסכמה חד משמעית (0.2). כדוגמה ספציפית, הם ציינו כי מספר מסדי נתונים ותורים מפתרונות קיימים אינם מכוסים בתיעוד. המפתח מסוגל לומר לאנליסט שלא הכל מתועד. אבל גם התזה לפיה מפתחים בודקים תיעוד לא זכתה לתמיכה חד משמעית (0.33). כלומר, הסיכון לתיאור לא שלם של פתרונות מיושמים נותר בעינו.

הרלוונטיות קלה יותר - למרות ששוב אין הסכמה ברורה (0,13), אנליסטים עדיין נוטים לשקול את התיעוד רלוונטי. ההערות אפשרו לנו להבין שבעיות עם רלוונטיות הן לעתים קרובות יותר בחזית מאשר באמצע. עם זאת, הם לא כתבו לנו שום דבר על גיבוי.

באשר לשאלה האם האנליסטים עצמם מבינים מתי יש צורך לכתוב ולעדכן תיעוד, ההסכם היה הרבה יותר אחיד (1,33), כולל עיצובו (1.07). מה שצוין כאן כחוסר נוחות הוא היעדר כללים אחידים לשמירה על תיעוד. לכן, כדי לא להפעיל את מצב "מי הולך ליער, מי מקבל עצי הסקה", עליהם לעבוד על סמך דוגמאות של תיעוד קיים. לפיכך, משאלה שימושית היא ליצור תקן לניהול מסמכים ולפתח תבניות עבור חלקיהם.

תיעוד עבור יישומי NIB עדכני בזמן ההגשה לתמיכה פונקציונלית (0.73). זה מובן, כי אחד הקריטריונים להגשת פרויקט לתמיכה פונקציונלית הוא תיעוד עדכני. זה גם מספיק כדי להבין את היישום (0.67), אם כי לפעמים נותרו שאלות.

אך מה שהמשיבים לא הסכימו איתו (די פה אחד) הוא שתיעוד עבור יישומי NIB, באופן עקרוני, נדרש רק לתמיכה תפקודית (-1.53). אנליסטים הוזכרו לרוב כצרכני תיעוד. שאר הצוות (המפתחים) - הרבה פחות. יתרה מכך, אנליסטים מאמינים שמפתחים אינם משתמשים בתיעוד כדי להבין מה הם צריכים ליישם, אם כי לא פה אחד (-0.06). זה, אגב, צפוי גם בתנאים שבהם פיתוח קוד וכתיבת תיעוד מתנהלים במקביל.

מהי השורה התחתונה ולמה אנחנו צריכים את המספרים האלה?

כדי לשפר את איכות המסמכים, החלטנו לעשות את הפעולות הבאות:

1. בקש מהמפתח לעיין במסמכים כתובים.
2. במידת האפשר, עדכן את התיעוד בזמן, קדם תחילה.
3. צור ואמץ תקן לתיעוד פרויקטים של NIB כך שכולם יוכלו להבין במהירות אילו רכיבי מערכת ואיך בדיוק יש לתאר. ובכן, פתח תבניות מתאימות.

כל זה אמור לעזור להעלות את איכות המסמכים לרמה חדשה.

לפחות כך אני מקווה.

מקור: www.habr.com