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