מחפש צרות | מיכאל שטאל

 אתגר השורה האחת

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

יכולת זו תסייע להם כשיצטרכו כבוגרים להעביר מסרים מורכבים בצורה קצרה וממצת. למשל: כתיבת כותרת למייל שחשוב שיקראו, כתיבת ציוץ ב-140 תווים, כתיבת הסבר על שינוי קוד במערכת לניהול גרסאות (git, p4, svn) , והכי חשוב (כמובן…): כתיבת כותרת לדו"ח על באג או למקרה בדיקה, במשפט אחד, קצר, קריא ומובן.

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

אחת השיטות שעוזרת להצליח בכתיבה מתומצתת היא הגדרת תבנית עבור המשפט הנדרש. שיטה זו של כתיבה נקראת כתיבה בשפה חופשית עם אילוצים (תרגום שלי ל – constrained natural language).

אתן כאן דוגמאות לשתי תבניות: עבור כותרת לבאג ועבור כותרת למקרה בדיקה.

כותרת לבאג

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

אז מי הם ה"לקוחות" של כותרת הבאג ולמה הם קוראים את הכותרת?

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

על פי רשימת הלקוחות אפשר להבין מהו המסר הרצוי להעביר במשפט אחד תמציתי:

  • מהי התקלה שנצפתה
  • האזור במוצר שבו נמצא הבאג
  • חומרת הבאג והדחיפות לתקן אותו

והנה ההצעה לתבנית:

[תסמין][פעולה][מצב מערכת]

תסמין (Symptom): מה קרה למערכת. מה ראינו, חווינו או מדדנו.

פעולה (action): מה עשינו שגרם לבאג להופיע.

"כשמנסים להעביר מסר בשפה יום-יומית, מאוד קל להתברבר"

מצב המערכת (operating conditions): תנאי העבודה של המערכת כאשר הבאג הופיע.

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

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

ועכשיו לדוגמאות:

השמעה של קבצי mp3 בגודל מעל mb100 נתקעת לאחר מספר שניות

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

"מי הם הלקוחות של כותרת הבאג ולמה הם קוראים את הכותרת?"

הכנסת ערך ריק לשדה Cursor Speed בקובץ הקונפיגורציה גורם למסך כחול (BSOD) במערכות 32 ביט

להדגמה איך שדות התבנית מופיעים בכותרות, אפשר ללמוד עוד כמה דברים מהדוגמאות:

  • זהירות מכפל משמעות. אם הייתי כותב את הכותרת הראשון ככה: "השמעה של קובץ MP3 בגודל מעל mb100 נתקעת לאחר מספר שניות", אפשר היה להבין את הבאג בשתי דרכים: כל קובץ מעל mb100 תוקע את התוכנה, או: יש קובץ מסויים שגורם לבעיה להופיע. על ידי שימוש בלשון רבים ("קבצי") המסר ברור יותר: הבעיה קורית עם כל קובץ גדול.
  • צריך לעשות מאמץ לכתוב משפט שמרגיש טבעי. משפט שהיינו אומרים, פחות או יותר, בשיחה רגילה על מנת לתאר משהו. אפשר היה לנסח את הדוגמה השנייה ככה: "הכנסה של שם משפחה אינה מתאפשרת כאשר אורכו של הקלט מעל עשרה תווים". המידע הוא אותו מידע, אבל השפה סבילה ("אינה מתאפשרת"). המשפט מכיל מילים מיותרות שסתם מאריכות אותו ובנוסף, השדות של התבנית מפוצלים עכשיו. המשפט בכללותו קשה יותר לקריאה. אפשר היה לכתוב קצר יותר: "שדה המשפחה מאפשר כתיבה של עד עשרה תווים". משפט המתאר נכון את המצב, אבל למי שקורא אותו לא ברור מיד מה הבעייה. הכל כתוב כל כך חיובי! איזה יופי ששדה המשפחה מאפשר עשר תווים! רק מי שיודע שהדרישה היא לשדה משפחה שמאפשר 16 תווים, מבין מה הבאג.

  • חשוב להכניס לכותרת מילות מפתח שנמצאות בשימוש נפוץ. לכן, בכותרת השלישית, לא הסתפקתי בכתיבת "מסך כחול" אלא הוספתי גם "BSOD". חלק מהבודקים יחפשו "מסך כחול" על מנת למצוא אם הבאג כבר דווח. אחרים יחפשו BSOD. יתכן שכדאי היה לכתוב bit32 ולא 32 ביט. תלוי כמה הארגון נוטה לשימוש במונחים בעברית לעומת אנגלית.

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

השמעה של קבצי mp3 בגודל מעל 100mb נתקעת לאחר מספר שניות. תדירות: 50% התאוששות: הפעלה מחדש.

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

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

"[באג חדש][דף רישום][פרוייקט X] שדה שם המשפחה לא מאפשר להכניס יותר מעשר תווים"

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

כותרת למקרה בדיקה

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

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

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

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

[הרכיב הנבדק] [פעולה] [מצב בדיקה] [תוצאה צפויה]

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

  • התחבר לרשת ה-WiFi
  • התחל להוריד קובץ גדול
  • סגור את ה-WiFi דרך תפריט ההגדרות
  • פתח את ה-WiFi דרך תפריט ההגדרות
  • חזור על כך מספר פעמים

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

הנה כותרות אפשריות לבדיקה זו:

  1. תיאור מקרה שימוש: "ניתוק וחיבור מחדש של WiFi תוך כדי הורדת קובץ"
  2. תיאור הליך בדיקה: "סבבים של ניתוק וחיבור WiFi תוך כדי הורדת קובץ"
  3. מטרת הבדיקה (תיאור הפונקציונליות המצופה): "התחברות מחדש של WiFi לאחר ניתוק בזמן הורדת קובץ".
  4. סיכון: "ה -WiFi  מסוגל להתחבר מחדש לאחר ניתוק תוך כדי הורדת קובץ" (זה מוודא שהסיכון "WiFi  לא מסוגל להתחבר מחדש לאחר ניתוק תוך כדי הורדת קובץ" לא מתקיים במוצר).

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

סיכום

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

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