הבלוג של ארתיום
בלוג על לינוקס, תוכנה חופשית, מוזיקה, סלסה, ומה לא!
תכנה חופשית, תיעוד ומה שביניהם
למרות שניסיון שלי בתחום פיתוח תכנה חופשית יכול להסתכם בכמה שנים של עובדה אקראית על פרויקטים שונים, למדתי משהו מאוד חשוב. לכתוב תכנה טובה, זאת משימה מאוד חשובה, אבל, זאת רק חצי מכל העובדה.
הבלוג הזה מתעסק בעיקר בתוכנה חופשית ופיתוח. חלק גדול מקוראי הבלוג, יודעים לכתוב קוד וגם יודעים לעשות את זה מצוין. אבל כמה מכם אוהבים לכתוב תיעוד? כמה מכם יודעים לפתוח מעבד־תמלילים, wiki או כל כלי אחר עם סיום העבודה ולתעד את השינויים: בממשק הספריות, לכתוב דוגמאות שימוש, הסברים על הבדלים מול הגרסה הקודמת? ממש לא כולם. מה שעוד יותר חשוב, רובינו, המפתחים, די סולדים מכתיבת המסמכים, אנחנו טובים בכתיבת הקוד, אבל לא בתיעוד.
במקרה הטוב, בודדים יקפידו על הכנה מוקדמת של תיעוד בעזרת Doxygen או כלי תיעוד פנימי אחר. הבעיה ב"תיעוד" כזה שהוא עוזר רק לאלו שכבר מבינים או מכירים את מבנה הקוד והספריות, אבל הוא לא עוזר לאלו שצריכים להבין כיצד להשתמש בו.
כבר יצא לי לזנוח רעיון של שימוש בכמה ספריות מאוד חזקות רק בגלל שלא היה להן תיעוד סביר; וגם יצא לי להתחיל להשתמש בספריה (שבדיעבד לא הייתה כל כך מוצלחת) שהיה לה תיעוד מסודר.
אני חושב שהדוגמה הקלסית בתחום היא ivritex. פיתוח מעולה שנותן תמיכה מצוינת בעברית, חסרת כל תיעוד בסיסי. התיעוד היחד שקיים לא מעודכן בעליל ומתייחס לגרסאות ישנות. מדריך המעודכן היחיד לעבודה עם lyx כל כך תמציתי שהייתי צריך לקרוא את תוכן הקבצים המומלצים על מנת להבין כיצד להחליף שפה. באתר הפרויקט אין שום זכר לחבילת גופנים עדכנית שיש להשתמש בה ועוד. מה התוצאה? כמות המשתמשים ב־LaTeX בעברית בארץ היא פשוט זניחה.
הערה: אני רוצה לטפל בנושא של תיעוד של ivritex בזמן הקרוב, אבל זה נושא אחר.
הדוגמה השנייה הקלסית היא FreePascal. כל תיעוד או מדריך שאפשר למצוא ברשת מתייחס ל-TurboPascal 7.0 במקרה הטוב. בעקבות המלצות הסברים של עידו רציתי ללמוד, מה השתנה ב־Pascal הזה בכל ה־Pascalים שיצא לי להכיר. הרי יש כל כך הרבה פונקציונליות חדשה שלא הייתה קיימת אז. לצערי, ויתרתי על הרעיון, כי פשוט זה בלתי אפשרי ללמוד משהו אם אין לך מאיפה ללמוד את זה.
אחת המסקנות החשובות מניסיוני הקצר היא: תיעוד לא פחות חשוב (אם לא יותר) מכתיבת קוד איכותי
גם אם יש לכם יישום מעולה, שיכול לשמש עשרות או מאות אנשים הוא יהיה חסר תועלת אם אי אפשר להבין כיצד להשתמש בו. למרות שרובינו, מפתחי התוכנה החופשית, עושים את זה בעיקר לצרכים שלנו, כדאי לנו להשקיע קצת יותר בתיעוד, כך נוכל לקבל גם עזרה וטלאים מאחרים.
גילוי נאות: גם אני לא תמיד כותב תיעוד, אבל לפחות, עבור תכנה שחושב לי שישתמשו בה, אני משתדל.
תגובות
ניסית את הכתובת הבאה: http://www.freepascal.org/docs-html/ref/ref.html ?
העניין בשפה כמו פסקל, זה שיש לך הרבה דיאלקטים, כדוגמת דיאלקט בורלנד, דיאלקט אפל, דיאלקט FPC ודיאלקט Wirth. ככה שהשאלה היא מה השתנה בדיאלקט מסויים, ולא מה השתנה מTP7
בתור אנטי טזה ל Javadoc: http://www.freepascal.org/docs-html/fpdoc/fpdoc.html
תודה, זה כבר משהו.
האמור לעיל נכון לא רק לגבי תוכנה חופשית, אלא לתכנה ככלל. פרויקט סמבה (www.samba.org) הוא דוגמא לפרויקט שהתעוד שלו מדהים, הן ברמת המשתמש והן ברמות של מנהל המערכת והמפתח.
אני מסכים,
רק העניין הוא שלרוב אני עובד עם תכנה קניינית בעבודה, ושם לא אני בחרתי כך שאני חי עם מה שיש וגם בד"כ אפשר למצוא אנשים שמכירים אותה.
כשאני בוחר רכיב תכנה חופשית, בד"כ הסיבה היחידה של העדפת ספריה/תכנה אחת על אחרת היא: איכות, תיעוד.
במקרה של תכנה קניינית, לא תמיד שני הרכיבים האלה הם הרלוונטיים ביותר.
הוסף תגובה:
חובה לאפשר JavaScript כדי להגיב.