תיעוד טכני אינו משימה משנית שמשלימים לאחר שהקוד עובר קומפילציה. הוא עומד במרכזו של כל פרויקט תוכנה, וקובע האם מפתח חדש יוכל לתקן באג כבר ביום הראשון שלו, או האם משתמש ינטוש את המוצר שלכם לאחר חמש דקות של בלבול. תיעוד טוב עוזר למשתמשים לבצע משימות אמיתיות. הוא עוזר למתחזקים עתידיים להבין מדוע מודול מסוים קיים וכיצד לשנות אותו מבלי לשבור הכל. ובכל זאת, צוותים רבים מדי מתייחסים לתיעוד כאל מחשבה מאוחרת, כאל קובץ README שנכתב בחיפזון, או כאל דף wiki שננטש לריקבון. כתיבת תיעוד מועיל באמת היא מיומנות שניתן לשפר באופן מכוון.
הכירו את הקוראים שלכם לפני שאתם כותבים
לפני שאתם מקלידים כותרת אחת, החליטו מי קורא. מנהל בסיסי נתונים המחפש הגדרות של connection pool לא שום דבר במשותף למפתח front-end המחפש props של רכיב React. משתמשי קצה זקוקים לשלבים ממוספרים ולצילומי מסך, לא לתרשימי ארכיטקטורה. הם רוצים לדעת איך לייצא PDF, לא איך עובד ה-rendering pipeline. מפתחים המשלבים את הספרייה שלכם זקוקים לחתימות פונקציה מדויקות, לקודי שגיאה ולמקטעי קוד (snippets) שניתן להעתיק ולהדביק. מנהלי מערכת זקוקים לדרישות קדם להתקנה, למשתני סביבה ולתהליכי פתרון תקלות המתחילים במצבי הכשל הנפוצים ביותר.
אם תנסו לשרת את כל שלוש הקבוצות באמצעות "קיר טקסט" אחד, כולם יפסידו. צרו מסלולים נפרדים. אפילו דף בודד יכול להיות מחולק בצורה ברורה באמצעות כותרות כמו "למפעילים" ו-"למפתחי לקוח". המטרה היא להסיר את החיכוך המנטלי של השאלה, "האם הפסקה הזו מיועדת לי?".
צמצמו את הרעש
בהירות מנצחת תחכום. השתמשו במשפטים קצרים. השתמשו בקול פעיל. "אתחל את בסיס הנתונים" ברור יותר מ-"בסיס הנתונים צריך להיות מאותחל על ידי המשתמש". כאשר עליכם להשתמש במונח טכני כמו "idempotency" או "serialization", הגדירו אותו בתוך הטקסט או הפנו למילון מונחים. אל תניחו שיש לקורא ידע מוקדם.
מבחן מעשי אחד: נסו לקרוא את הפסקה שלכם בקול רם. אם נגמר לכם הנשימה, המשפט ארוך מדי. מבחן נוסף: החליפו פעלים מליציים בפעלים פשוטים. אם ביטוי כמו "utilize the API" יכול להפוך ל-"use the API" מבלי לאבד את המשמעות, בצעו את השינוי. שפה פשוטה אינה אומרת שפה מופשטת. היא אומרת שפה מדויקת שנושלה מ"מילוי" תאגידי מיותר.
מבנה שעוזר באמת
מדריך לא מאורגן מבזבז יותר זמן מאשר היעדר מדריך לחלוטין. חשבו על התיעוד שלכם כעל משפך. בחלק העליון, הציבו סקירה קצרה המסבירה מה הפרויקט עושה ולמי הוא רלוונטי. לאחר מכן, הוסיפו הוראות התקנה שאינן מניחות דבר לגבי הגדרות המערכת המקומית של הקורא. לאחר מכן, הוסיפו מדריכים (tutorials) שעוברים על תרחישים מלאים וריאליסטיים מתחילתם ועד סופם. מדריכי API מגיעים לאחר מכן. אלו צריכים להיות מקיפים אך ניתנים לסריקה מהירה, מקובצים לפי משאב או פונקציה במקום להיערם בסדר אלפביתי. לבסוף, הציבו מדריכי פתרון תקלות המתייחסים לתסמינים ספציפיים. משתמש שמקבל "Connection refused" זקוק לתשובה שונה מזו של משתמש שרואה "Permission denied". קבצו שגיאות לפי הודעה או לפי הקשר, ולא לפי קטגוריה מופשטת.
רשימות ובלוקים של קוד שוברים טקסט צפוף ומאפשרים לקוראים לסרוק ולמצוא את הפקודה המדויקת שהם צריכים. רשימת תבליטים במקום הנכון יכולה להפוך פסקה מבלבלת לרצף של פעולות.
הראו, אל תסתפקו רק בתיאור
הסברים מופשטים מתסכלים משתמשים. אם אתם מתארים כיצד להגדיר כלי, הראו את תוכן הקובץ המדויק. ספקו מקטעי קוד להתקנה, לאתחול ולהגדרות נפוצות. הציגו קלטים לדוגמה ופלטים צפויים זה לצד זה. אם ה-API שלכם מחזיר JSON, הראו JSON. אם כלי CLI מייצר פלט טבלאי, הראו טבלה. לעולם אל תניחו שתיאור של תהליך עבודה שווה להדגמה.
והחשוב מכל, בדקו כל דוגמה בסביבה נקייה לפני שאתם מפרסמים אותה. העתיקו את מקטע הקוד שלכם לתוך קונטיינר או מכונה וירטואלית חדשה. אם זה נכשל כי שכחתם לציין תלות (dependency), חסכתם לעצמכם שטף של בעיות. דוגמאות קונקרטיות מספקות את ההחזר הגבוה ביותר על ההשקעה בכתיבה טכנית, כיוון שהן הופכות חוסר ודאות לפעולה.
שמרו על זה חי
תיעוד מתכלה מהר יותר מקוד. חתימת מתודה משתנה, פורט ברירת מחדל עובר, תלות מוחלפת, ופתאום ההוראות שלכם מובילות למבוי סתום.