תיעוד שאנשים באמת קוראים

ארבעה מסמכים שמספיקים

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

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

מפעילים. מה עושים כשמשהו נשבר, איך פורסים, איך חוזרים אחורה.

ממשק. מתוך הקוד, כדי שלא יתיישן.

איך שומרים על טריות

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

מה לא לתעד

מה שהקוד אומר בבירור. הערה שמתארת שורה מיותרת; הערה שמסבירה למה נבחרה גישה מוזרה — יקרה מזהב.