אתגר השורה האחת
מצב מוכר: הילדה חזרה מביתה של אחת החברות שלה שם הן בילו בצפייה בסרט. אם אתם הורים מתחילים שמנסים להיות מעורבים בחיי הילדים, מיד תבקשו שתספר על מה היה הסרט. אבל אם אתם בג'וב הזה כבר כמה שנים (או: אם תקראו את שני המשפטים הבאים), אתם יודעים ששאלה תמימה זו עלולה למלא את עשרים הדקות הבאות בפרטי פרטים של כל סצנה בסרט. ולכן אני מציע לאתגר אותה: "ספרי לי על מה היה הסרט, בחמישה משפטים". הרווח כאן הוא משולש: הדיווח על הסרט יהיה קצר, הילדה לומדת לספור עד חמש... והרווח האמיתי (בלי ציניות) זה פיתוח היכולת של הילדים לתמצת.
יכולת זו תסייע להם כשיצטרכו כבוגרים להעביר מסרים מורכבים בצורה קצרה וממצת. למשל: כתיבת כותרת למייל שחשוב שיקראו, כתיבת ציוץ ב-140 תווים, כתיבת הסבר על שינוי קוד במערכת לניהול גרסאות (git, p4, svn) , והכי חשוב (כמובן…): כתיבת כותרת לדו"ח על באג או למקרה בדיקה, במשפט אחד, קצר, קריא ומובן.
כשמנסים להעביר מסר מורכב בשפה יום-יומית, מאוד קל להתברבר, להוסיף מילים מיותרות, להסתבך עם תחביר משונה ובאופן כללי לייצר משפט ארוך ובעל יותר ממשמעות אחת. ההפך מזה הוא השימוש בשפה פורמלית, שבה כל פרט מוגדר בצורה מלאה. המסר אמנם יהיה חד משמעי ומדויק, אבל התוצאה אינה קריאה למי שאינו מכיר את כללי השפה.
אחת השיטות שעוזרת להצליח בכתיבה מתומצתת היא הגדרת תבנית עבור המשפט הנדרש. שיטה זו של כתיבה נקראת כתיבה בשפה חופשית עם אילוצים (תרגום שלי ל – constrained natural language).
אתן כאן דוגמאות לשתי תבניות: עבור כותרת לבאג ועבור כותרת למקרה בדיקה.
כותרת לבאג
לצורך הגדרת תבנית מועילה, חשוב לדעת מי הם המשתמשים העיקריים במידע המופיע בכותרת של באג, להבין מה המידע שנחוץ למשתמשים אלא, ומשם הדרך להגדרת התבנית קצרה.
אז מי הם ה"לקוחות" של כותרת הבאג ולמה הם קוראים את הכותרת?
על פי רשימת הלקוחות אפשר להבין מהו המסר הרצוי להעביר במשפט אחד תמציתי:
והנה ההצעה לתבנית:
[תסמין][פעולה][מצב מערכת]
תסמין (Symptom): מה קרה למערכת. מה ראינו, חווינו או מדדנו.
פעולה (action): מה עשינו שגרם לבאג להופיע.
"כשמנסים להעביר מסר בשפה יום-יומית, מאוד קל להתברבר" |
מצב המערכת (operating conditions): תנאי העבודה של המערכת כאשר הבאג הופיע.
חשוב לציין שהתבנית מגדירה "שדות" (פרטים) שצריכים להופיע בכותרת, ואילו הסדר אינו קריטי כלל. כל זמן שהמידע שהתבנית ממליצה עליו מופיע במשפט – כל סדר הוא בסדר. השדות מופיעים בתבנית בסדר מסוים כי אין ברירה – משהו הרי צריך להיות ראשון.
לפני שאתן כמה דוגמאות, אציין ש"מצב המערכת" הוא שדה רשות וישנם מקרים שכותרת הבאג ברורה לחלוטין גם בלי לציין את מצב המערכת. למשל כאשר הבאג מופיע תמיד, בלי תלות במצב המערכת; או כאשר ההגיון אומר שמצב המערכת לא קשור לבאג. לעיתים מצב המערכת לא ניתן לתאור בכמה מילים. במקרה כזה עדיף לכתוב משהו כללי (למשל "בקונפיגורציה מסויימת" או "במצב מסויים"). זה מעביר את המסר שהבעייה לא משתחזרת בכל קונפיגורציה, ולא מעמיס את הכותרת. כמובן שבמקרה כזה צריך לתת פרטים מלאים על מצב המערכת בגוף הדו"ח.
ועכשיו לדוגמאות:
השמעה של קבצי mp3 בגודל מעל mb100 נתקעת לאחר מספר שניות
שדה שם המשפחה לא מאפשר להכניס יותר מעשר תווים
"מי הם הלקוחות של כותרת הבאג ולמה הם קוראים את הכותרת?" |
הכנסת ערך ריק לשדה Cursor Speed בקובץ הקונפיגורציה גורם למסך כחול (BSOD) במערכות 32 ביט
להדגמה איך שדות התבנית מופיעים בכותרות, אפשר ללמוד עוד כמה דברים מהדוגמאות:
התבנית שנתתי כאן אינה תורה מסיני. אפשר להגדיר תבניות אחרות או להוסיף שדות. למשל, בקבוצה איתה עבדתי בעבר נהגו גם להוסיף שדה של תדירות, אם הבעיה לא מופיעה תמיד, ולעיתים גם את תיאור ההתאוששות מהבאג. למשל:
השמעה של קבצי mp3 בגודל מעל 100mb נתקעת לאחר מספר שניות. תדירות: 50% התאוששות: הפעלה מחדש.
אישית אני לא מת על זה וחושב שזה מאריך את הכותרת ללא צורך. עם זאת אני מסכים שלפעמים חשוב להעביר מסר על התדירות (במיוחד אם הבאג קורה רק לעיתים רחוקות, כדי שלא יסגרו אותו על "לא משתחזר"), ואז אפשר להוסיף משהו כגון "לעיתים רחוקות".
אם כבר מזכירים דברים שאני חושב שלא שייכים לכותרת, אזכיר את המנהג הנפסד לנסות לנהל את הבאגים בתוך הכותרת: לשייך אותם לפרוייקט, לסמן מה הסטטוס שלהם או לשייך אותם לפונקציונאליות:
"[באג חדש][דף רישום][פרוייקט X] שדה שם המשפחה לא מאפשר להכניס יותר מעשר תווים"
בשביל זה יש שדות בתוך הטופס לדיווח על הבאג. הכותרת צריכה להיות קצרה וקריאה. אם ממש ממש חשוב למנהלי הפרוייקט לקבל רשימת כותרות כזאת, אפשר לייצר אותה בשאילתה פשוטה על מאגר הבאגים שאוספת את המידע משדות שונים ומדפיסה קובץ עם כותרות מורכבות.
כותרת למקרה בדיקה
גם לגבי מקרי בדיקה כדאי לחשוב מי הם הצרכנים. הבודקים הינם הלקוח הטריוויאלי – כולל מי שמחליטים על התוכן של סבבי בדיקות, ובוחרים איזה בדיקות להריץ. לקוחות אחרים הם:
על מנת לספק את הצרכים של כל הלקוחות, צריך לתת מושג מה נבדק ובאיזה תנאים, וכמובן לעשות את כל זה במשפט אחד, קל לקריאה ורצוי קצר. אתגר לא פשוט.
מקרה בדיקה מממש תרחיש מסוים. זה יכול להיות מקרה שימוש, אבל גם יכול להיות תיאור של הליך בדיקה. באותה מידה ניתן לומר על מקרה בדיקה שיש לו מטרה מסוימת (לוודא ש...), או לבדוק שסיכון מסויים לא התממש. כיוון שכך, יש ארבע דרכים לתאר כל מקרה בדיקה: תיאור התרחיש, תיאור הליך הבדיקה, תיאור המטרה או תיאור הסיכון. מסתבר כי אותה תבנית מתאימה לארבעת האפשרויות. כמו בתבנית של כותרת באגים, גם עבור מקרה בדיקה לא תמיד חייבים להשתמש בכל השדות וכמובן שלא בהכרח בסדר שהם מופיעים בתבנית:
[הרכיב הנבדק] [פעולה] [מצב בדיקה] [תוצאה צפויה]
דוגמה: מקרה הבדיקה הבא נועד להבטיח שטלפון נייד מתחבר חזרה לרשת WiFi לאחר שהמשתמש כיבה והדליק את ה-WiFi, במקרה שבו הטלפון היה באמצע הורדת קובץ מהרשת. צעדי הבדיקה הם:
תוצאה צפויה: הטלפון מתנתק כשסוגרים את ה-WiFi, ומתחבר כשפותחים אותו. אין דרישה שהורדת הקובץ תתחדש אוטומטית.
הנה כותרות אפשריות לבדיקה זו:
כל הכותרות האלה באות בחשבון. אפשר גם לראות (לפי הצבעים) את קיומם של השדות של התבנית. מי מהכותרות מתאימה יותר הוא במידת מה עניין של העדפה אישית, אבל בעיקר נגזר מכך שלעיתים קל יותר לתאר משהו כתרחיש, ולעיתים אחרות – כהליך, מטרה או סיכון. אם רוצים להדגיש את התוצאה המצופה, כנראה שאפשרות (4) עדיפה. אם רוצים להדגיש את התנאים, אפשרות (2) מספקת יותר מידע. כהערה אחרונה אציין שחשוב להיגמל מהנטייה הטבעית להתחיל את הכותרת ב "וידוא ש..." או "בדיקה ש..." . זה מסרבל את הכותרת וגם מיותר: הרי ברור שכל מקרה בדיקה נכתב לצורך בדיקה או וידוא של משהו.
סיכום
כתיבה של כותרת טובה היא סוג של אומנות. משפט קצר שהוא מעט המכיל את המרובה. אם אתם מוצאים את עצמכם משקיעים כמה דקות טובות בכתיבה, מחיקה וכתיבה מחדש של כותרת לבאג או למקרה בדיקה זה לא בגלל שאין לכם מושג. זה בגלל שזה לא פשוט. להפך – יותר מדאיגים אותי הבודקים שלא משקיעים מחשבה בכותרת, ומסתפקים ב"קריסה של היישום" לכותרת של באג או "בדיקה מספר 172" ככותרת למקרה בדיקה.
כמו שהזכרתי בהתחלה, אומנות הקיצור נוגעת גם לכתיבת משפט נושא למייל. משפט שמעורר את הסקרנות כך שלמרות העומס היום-יומי ומבול של מיילים כולם יקראו אותו. כאן לפחות יש תשובה ברורה ופשוטה: תכתבו "בירה בחינם".