צ'ק ליסט לכתיבת מסמך בדיקות התקנה (STD Checklist)

פעמים רבות אנו הבודקים מזניחים את בדיקות ההתקנה ובדיקות הוראות/מסמכי ההתקנה, כשלמעשה זהו אחד החלקים החשובים ביותר בהעמדת המערכת ובשיווקה. ברור שאנו מתקינים את המערכת במהלך הבדיקות, וברור שאנו עורכים בדיקות קיט (אני מקווה), וכנראה בסביבות שונות. כמו כן ברור שבמידה שלא ניתן לסיים את ההתקנה אנו נתריע על כך כדבר קריטי. אבל זהו מסלול אחד של בדיקות, ופעמים רבות – זה אינו המסלול היחידי.

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

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

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

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

ראיתי מסמכי התקנה עם תמונות שאינן רלוונטיות יותר, עם שורות הרצה "דוסיות" ארוכות שיש להעתיק אות-אחרי-אות, מונחים לא ברורים וכד'. פעם אפילו עם משפט כזה: "במידה ונתקלתם בבעייה תשאלו את יוסי כהן (שם בדוי), בטל' 054-1111111 ", כשאותו "יוסי" הוא הבודק היחידי שמכיר את העניין ושבהחלט אינו אמור ואינו יודע לענות לבעיות של לקוחות - ואני לא מגזים!

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

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

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

בנקודה זו כבר היה ברור לנו שעלינו כבודקים (למרות שהבעיה היא רוחבית) לערוך מהפכה בנושא: קודם כל מהפכה תפיסתית, אח"כ מעשית.

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

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

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

בכל אופן, בסוף זה היה משתלם ומסמכי ההתקנה וההתקנה עצמה שופרו ללא הכר.

וכעת לעיצות מעשיות יותר:

דבר ראשון: בכל מקום שאפשר - יש לארגן מה שנקרא  "one click installations"שכשמו כן הוא: לוחצים על כפתור אחד (גם שלשה זה בסדר J) וכל השאר הוא אוטומאטי (לפחות פר שרת). זהו תהליך פיתוח רגיל של אפיון, פיתוח ובדיקות.

דבר שני, וכשכבר אנו חושבים שההתקנה טובה, יש לזכור את קהל היעד. לכן מומלץ מידי פעם להביא לבדיקות אלה בודק (או מישהו אחר) בעל רקע מתאים שלא התקין את המערכת הזו מעולם ולתת לו לעשות זאת בעצמו (ובהשגחה שקטה – מעיין מבחן יוזביליות).
בנוסף, וזה עניין שצריך להתחיל בדרישות ואם אין התייחסות אזי עלינו לדרוש את זה בתהליך ההתקנה: עלינו לוודא שניתנה הדעת  לשני הנושאים הבאים:
Fallback –  כלומר אם לא הצלחנו בדרך א' יש לנסות דרך ב'.
Rollback -  במידה וההתקנה פשוט לא מצליחה - אפשר לחזור בבטחה למצב טרום ההתקנה.

ברור שאנו לא רוצים להגיע לאף אחד מהמצבים הללו, אך עלינו להיערך להם.
מבחינת הבדיקות זה "סיוט" לבדוק התקנה טובה (דווקא!), כלומר בנוייה היטב, של מערכת גדולה, כי כמות ה-fallbacks וה-rollbacks היא אדירה. כל שרת בתת-מערכת לחוד, ואולי גם ביחד של כל אחד מהמצבים האלה. יש לבצע כמובן אופטימיזציה וניהול סיכונים.

ולבסוף: יש שני מצבים של הרצת מסמך בדיקות ושנייהם חשובים: dry run וכמובן הרצה בפועל. מטרת הdry run היא למנוע מאיתנו הרצה של שלשת-רבעי המסמך (ויום בדיקות) בכדי להבין שמשהו חסר, משהו שהיה אפשר להבין מתוך דפדוף במסמך בזמן של עשרים דקות.

מצ"ב צ'ק ליסט לעקרונות בדיקת התקנות:
דיוק:

כמו בבכל TD - ההתקנה עובדת בהתאם לדרישות.
בהירות:

1.                  המונחים וראשי התיבות שמשתמשים בהם בתהליך ההתקנה מוסברים.

2.                  שפה ברורה ותמציתית.

3.                  הפעולות והתוצאות ברורות וחד משמעיות.

4.                  ישנן תמונות להמחשה כולל סימנים בתמונות שיבהורו בדיוק מה יש לעשות.

5.                  אם ישנן כמה אפשרויות – להסביר כל אפשרות ובמה היא שונה מהאחרות.

שלמות:

1.                  שום צעד אינו חסר.

2.                  הצעדים הם לפי הסדר (חשוב מאוד!)

3.                  דרישות הקדם מצויינות.

4.                  שגיאות אפשריות ופרוצדורות של recovery מצויינות במסמך.

5.                  ציון של כמה זמן אמור לקחת כל תהליך.

6.                  הסבר של שיטות ההתקנה (ידניות, הרצות של exe וכד')

קונסיסטנטיות

1.                  פנה את קהל היעד שלך כיאות (אם אלו אינם אנשים טכניים אל תצפה שיבינו מונחים כמו batch file לדוגמא).

2.                  הפעולות והתוצאות כתובות בצורה עקבית עם הפירוט המתאים, ובאותו פורמט.

3.                  התהליך והמעבר בין הנושאים הם לוגיים, אין קפיצות מנושא לנושא.

תצורה גראפית:

1.                  Toolbars , תפריטים, פקודות ואפשרויות פועלים בדיוק כמו במסמך.

2.                  ברירות המחדל במסמך וב-GUI זהות.

3.                  דוגמאות מתועדות נכון.

ארגון:

1.                  יש אזכור של מסמכים קשורים.

2.                  מטרות כל תהליך מוסברות.

3.                  יש overview של ההתקנה.

4.                  לא יותר מ-10 עד 15 צעדים בכל פרוצדורה.

5.                  הצעדים ממוספרים.

6.                  מינימום של פעולות ידניות.

7.                  יש מקום להערות וחתימה של הבודק.

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

9.                  המשך של #8: אפשר ורצוי גם לתת טיפים. את זה אפשר להשאיר ליד המקום הרלוונטי, אבל בקצרה ובפורמט וצבע שונים עם תיוג ברור.

סטייל:

1.                  נראה מקצועי.

2.                  משתמש במונחים מקצועיים.