״הכלי מעולה אבל התיעוד לוקה בחסר״ ״לקח לי יותר משעה למצוא דוגמא נורמלית שעובדת״ ״אני מנסה ללמוד דג'נגו והתיעוד רץ ב 100 קמ"ש ובלי שום תמונות״

אני יודע שזה מתסכל להתחיל לקרוא תיעוד על ספריה ולא להבין כלום. זה קרה לי עם NumPy וגם עם Active Records בהתחלה וכמובן בכל מה שקשור ל CSS. הבעיה היא אף פעם לא היעדר תיעוד (אף אחד לא מתלונן על תיעוד ה API של iCount), אלא ספריות עם תיעוד ארוך, קיים, שאני פשוט לא מבין אותו.

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

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

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