בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- ScummVM
- כותבים טכניים:
- b-gent
- שם הפרויקט:
- שיפור התיעוד של קוד המקור באמצעות Doxygen
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
המסמכים הנוכחיים של ScummVM API (קוד המקור) מתפרסמים כאן: https://doxygen.scummvm.org/modules.html
לצערנו, הוא חסר בתחומים רבים:
1) אין לממשק כמעט מבנה, וכל המידע נמצא באותה רמה.
2) התיעוד של רכיבי C++ לא עקבי, וחלק מהם לא מתועדים בכלל. זו אחת מהבעיות העיקריות שהארגון מציין.
3) תוכן מיושן ותוכן שהוצא משימוש עדיין מוצגים בפלט.
4) השפה והשימוש בתיוג של Doxygen צריכים להיות עקביים יותר. לשם כך נדרשת קבוצת כללים, שיכולה לשמש כבסיס למדריך סגנון עתידי למסמכי התיעוד של הפרויקט.
5) אפשר לשפר את קובץ ה-CSS של doxygen שמשמש בדף הזה כדי שיהיה דומה יותר לאתר של ScummVM: https://www.scummvm.org
אפשר לפתור את כל הבעיות האלו במהלך העונה של פרויקט Docs.
הבקשה לעונה הזו של Docs מלווה בטיוטת PR שפתחתי בפרויקט כדי להדגים כמה שיפורים אפשריים שאני מציע: https://github.com/scummvm/scummvm/pull/2361 עיינו בתיאור כדי לקבל פרטים על מה שהוא מכיל ולראות את ההבדלים.
אלה בערך השלבים של יחסי הציבור:
1) לדעתי הדבר הכי מבלבל כרגע בקרב תורמים פוטנציאליים חדשים, ובאופן כללי כל מי שצופה במסמך ה-API הנוכחי, הוא היעדר המבנה. הוספת תיעוד מובנה של ממשקי API תשפר את הקריאוּת, את היכולת למצוא את המסמכים ואת נוחות השימוש בקבוצת המסמכים. לכן בבקשת העריכה שלי הוספתי קבוצות doxygen לכל קובצי הכותרות בתיקייה 'common'. במבנה החדש, אם מישהו רוצה למצוא מסמכים של ממשקי API שקשורים למערכת ההפעלה (לדוגמה), הוא יכול למצוא אותם בקלות בתפריט הניווט.
2) קובץ תצורה חדש של Doxygen מוגדר כדי לאפשר את היצירה של המסמכים האלה.
3) קובץ 'links.doxyfile' שממנו אפשר לקבל את כל הקישורים שמשמשים ב-docset מתוך מקור יחיד. מנגנון שימושי לעבודה עם doxygen.
4) קובץ CSS של doxygen שעבר שינוי. הפרויקט הזה נלקח כרגע מפרויקט אחר בקוד פתוח, וזו רק נקודת ההתחלה. באופן אידיאלי, המראה והתחושה של דף ה-Doxygen צריכים להתאים יותר או פחות לדף האינטרנט של ScummVM.
מה שיחסי הציבור לא מכסים, אבל עליכם לטפל בו בהחלט, הוא התוכן עצמו. הכוונה היא לזהות את החלקים החיוניים בקוד שלא מתועדים, את החלקים שלא מתועדים בצורה מספקת או את החלקים המיושנים בקוד שצריך להסיר מהתיעוד. מאחר שלא עבדתי בפרויקט הזה בעבר, אצטרך הדרכה ממנטור כדי להשיג זאת.
כמובן, ההחלטה אם ליישם משהו מהבקשה תלויה בשיחה עם הארגון. הרעיון שלי היה שפעולות מדברים יותר מאשר מילים, ולכן החלטתי להראות מה אני יכול לעשות במקום רק לתאר את זה באפליקציה.
הארגון סיפק את לוח הזמנים המשוער הבא לפרויקט: שבוע המשימה הראשית שבוע 0 (לפני 14 בספטמבר) דיון בבקשה וביקורות עליה שבוע 1 (14 בספטמבר) הגדרת build של Doxygen שבוע 2 (21 בספטמבר) רענון של עורכת Doxygen (עדיפות נמוכה) שבוע 3 (28 בספטמבר) קוד משותף – OSystem, FS, Data Structures, Strings וכו' שבוע 4 (5 באוקטובר) קוד משותף – המשך שבוע 5 (12 באוקטובר) מנועי חיפוש – קוד משותף ומנוע חיפוש לדוגמה שבוע 6 (19 באוקטובר) גרפיקה שבוע 7 (26 באוקטובר) אודיו שבוע 8 (2 בנובמבר) וידאו, תמונות שבוע 9 (9 בנובמבר) קצוות עורפיים – פלטפורמות, גרפיקה, אירועים שבוע 10 (23 בנובמבר) קצוות עורפיים – המשך שבוע 11 (30 בנובמבר) סיכום הפרויקט ושליחתו
השינוי היחיד שאציע הוא להתחיל לעבוד על המבנה, כפי שציינתי קודם. אפשר לעשות זאת בשבועות 1 ו-2, יחד עם הגדרת ה-build של Doxygen (כבר בוצעה במידה רבה) ורענון העיצוב של Doxygen. לאחר מכן, אני מסכים שהכי הגיוני לעבור על האזורים השונים אחד אחרי השני עם המנטור כדי לזהות בעיות ולשפר את התיעוד של Doxygen.
אני רואה את הפרויקט באורך רגיל אבל אני בטוחה שיש שיפורים נוספים שקשורים למסמכי התיעוד של ה-API שאפשר לבצע אחרי שפרויקט GSoD יסתיים. לדוגמה, אפשר ליצור מדריך סגנון לתיעוד ולהוסיף אותו לוויקי, כדי שתורמים ידעו איך לתעד את הקוד שהם מוסיפים.
אשמח לעזור במשימות כאלה אחרי ש-GSoD יסתיים. אני בטוח ש-ScummVM יכולה להשתמש בכותב טכני שידאג שהמסמך של ממשק ה-API יהיה באיכות טובה ובנוחות שימוש. אני רואה שיש פרויקטים אחרים של מסמכי עזרה שאוכל לעזור לך איתם בעתיד, כמו יצירת מדריך לעבודה עם פלאגינים.