כתיבת הנחיות שבונות היטב

מה באמת צריך להיות בהנחיית בנייה?

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

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

האם אני צריך לציין למי זה מיועד?

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

כמה דרישות חובה עלי לרשום?

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

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

האם עלי לציין אווירה?

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

למה לא פשוט לתאר כל מה שאני חושב/ת?

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

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

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

איך נראה פרומפט טוב בפועל?

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

מה אם כבר יש לי צבעי מותג או תמונות אמיתיות?

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