דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- ScummVM
- כתב טכני:
- b-gent
- שם הפרויקט:
- שיפור התיעוד של קוד המקור באמצעות Doxygen
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
התיעוד הנוכחי של ScummVM API (קוד המקור) פורסם כאן: https://doxygen.scummvm.org/modules.html
לצערנו, חסר מידע לגביה בתחומים רבים:
1) אין כמעט מבנה כזה, כל המידע צף באותה רמה.
2) רכיבי C++ מתועדים באופן לא עקבי עם חלק מהם שאינם מתועדים כלל. בארגון מציינים את זה כאחת מהבעיות העיקריות.
3) תוכן מיושן או שהוצא משימוש עדיין מוצג בפלט.
4) צריך לשמור על עקביות בשפה של תיוג חמצן ובשימוש בו. לשם כך יש צורך בקבוצה של כללים, משהו שעשוי להוות בסיס למדריך סגנון לתיעוד עתידי עבור הפרויקט הזה.
5) ניתן לשפר את ה-CSS של Doxygen שבו נעשה שימוש בדף הזה כדי שיהיה דומה יותר לאתר ScummVM: https://www.scummvm.org
ניתן להתמודד עם כל הבעיות האלו במהלך העונה של פרויקט Docs.
אפליקציית Docs לעונה זו מלווה בטיוטה של 'יחסי ציבור' שפתחתי בפרויקט כדי להמחיש את השיפורים האפשריים שאני מציע: https://github.com/scummvm/scummvm/pull/2361 ניתן לעיין בתיאור כדי לקבל פרטים על מה שהוא מכיל ולראות את ההבדלים.
פחות או יותר:
1) לדעתי מה שמבלבל ביותר כרגע תורמים פוטנציאליים חדשים, ובדרך כלל כל מי שצופה במסמך הנוכחי של ה-API הוא היעדר המבנה. הוספת תיעוד מובנה של API תשפר את הקריאוּת ואת יכולת האיתור, וכתוצאה מכך תשפר את נוחות השימוש במסמך. לכן מחלקת יחסי הציבור שלי מציגה קבוצות חמצן לכל קובצי הכותרת בתיקייה 'Common'. בעזרת המבנה החדש, אם מישהו רוצה למצוא מסמכים עבור API הקשור למערכת ההפעלה (לדוגמה), הוא יוכל למצוא אותו בקלות בניווט.
2) הגדרת קובץ תצורה חדש של Doxygen כדי לאפשר את בניית התיעוד הזה.
3) קובץ 'links.doxyfile' שממנו כל הקישורים המשמשים את המסמך יכולים להגיע ממקור יחיד. מנגנון שימושי לעבודה עם חמצן.
4) CSS עם נתוני חמצן שהשתנה. הדוגמה הזו נלקחה מפרויקט קוד פתוח אחר, ומהווה רק נקודת התחלה. באופן אידיאלי, המראה והתחושה של דף doxygen צריכים להיות תואמים יותר או פחות לדף האינטרנט של ScummVM.
מחלקת יחסי הציבור לא כוללת את הנושא הזה, אבל בהחלט טעונות אותו בתוכן עצמו. הכוונה היא לזהות את החלקים החיוניים בקוד שלא מתועדים, את החלקים שלא מתועדים כראוי או את החלקים המיושנים בקוד שצריך להסיר מהתיעוד. מכיוון שלא עבדתי בעבר על הפרויקט, יהיה צורך בהדרכה ממנטור כדי לעשות זאת.
כמובן, ההחלטה אם ניישם משהו ממחלקת יחסי הציבור היא עדיין בדיון עם הארגון. הרעיון שלי היה שדברים מדברים בקול רם יותר ממילים, לכן החלטתי להראות מה אפשר לעשות במקום לתאר את זה באפליקציה בלבד.
הארגון סיפק את ציר הזמן המשוער הבא (20 שעות/שבוע 2) לפרויקט הזה, משימה ראשית 17/שבוע (2019/2) (שבוע 1)/10 משימות נוספות
השינוי היחיד שאני מציע הוא להתחיל בעבודה על המבנה, כפי שכבר ציינו. אפשר לעשות את זה בשבועות 1 ו-2, לצד ההגדרה של מערכת החמצן (שבדרך כלל כבר מתבצעת) ורענון העור בעזרת Doxygen. אחר כך, יותר הגיוני לעבור על התחומים השונים אחד אחרי השני עם המנטור כדי לזהות בעיות ולשפר את התיעוד לגבי חמצן.
אני רואה את הפרויקט הזה באורך סטנדרטי, אבל אני בטוח שיש שיפורים נוספים שקשורים לתיעוד ה-API לאחר סיום הפרויקט של GSoD. לדוגמה, להכין מדריך סגנון לתיעוד ולהוסיף אותו ל-wiki, כדי שהשותפים ביצירת התוכן ידעו כיצד עליהם לתעד את הקוד שהם מוסיפים.
אשמח לעזור במשימות כאלה אחרי ש-GSoD יסתיים. אין לי ספק ש-ScummVM יוכל להיעזר בכתב טכני שיוודא שמסמך ה-API שלו באיכות טובה ובשימושיות. אני רואה גם שיש פרויקטים עתידיים של Docs שאוכל לעזור לך בהם, כמו יצירת מדריך לעבודה עם יישומי פלאגין.