בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- CERN-HSF
- כותבים טכניים:
- John
- שם הפרויקט:
- CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials
- אורך הפרויקט:
- Long running (5 months)
תיאור הפרויקט
CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials מנטור: Olivier Couet, Axel Naumann
תקציר: תיעוד הוא חיוני להטמעה מוצלחת ויעילה של תוכנות על ידי משתמשים. מסמכי עזרה ברורים, מדויקים ומקיפים עוזרים למשתמשים להשתמש בתוכנה בצורה יעילה יותר ולהגיע ליעדים שלהם. בנוסף, דוגמאות ומדריכים מפורטים משמשים ככלים יעילים שבעזרתם המשתמשים יכולים ללמוד במהירות.
כשאנחנו בודקים את השימוש ב-ROOT על ידי פיזיקאים, חוקרים ומפתחים במרחב של ניתוח נתונים ותצוגה חזותית בפיזיקה, אנחנו מבינים את היתרונות של תיעוד ידידותי למשתמש ומעודכן. במיוחד, בגלל היקף קוד המקור והצמיחה שלו, מערכת המסמכים עשויה להפיק תועלת מהתקדמות במקביל כדי לאפשר למשתמשים למקסם את כל מה ש-ROOT מציעה.
סיכום וניתוח של המסמכים הקיימים נכון לעכשיו, במסמכי העזרה למשתמש יש מדריך שמאפשר לפיזיקאים להשתמש ב-ROOT בקלות רבה יותר בהשוואה לקהל הרחב. בנוסף, בנושאים מסוימים כמו קישורי Python דינמיים, אפשר לבצע שיפורים כדי ליצור תיעוד מקיף וברור יותר. באופן דומה, בפורמט הנתונים החדש RNTuple חסרים מפרטים מפורטים הנדרשים. לבסוף, בתיעוד הנוכחי חסרים מדריכים שקשורים ל-ROOT 7.
מתודולוגיה: לאחר התייעצות עם Olivier, נראה שכדי לטפל בבעיות שהוזכרו למעלה, צריך להתמקד בעיקר בזיהוי פערי הידע בין חוקרים מומחים לבין קהל כללי, יצירת מסמכים לגשר על הפער הזה, כתיבת תיעוד מפורט יותר של קישורי Python דינמיים, הטמעת 'מדריכים לניתוח נתונים מודרני' עבור ROOT 7 ויצירת מפרטים טכניים מפורטים עבור RNTuple. לאורך התהליך הזה, מסמכי התיעוד יכולים לשלב notebooks של Jupyter כדי לאפשר למשתמשים להיעזר בכלי למידה מוחשיים ואינטראקטיביים.
ציר זמן: השלבים המשוערים של הפרויקט: זיהוי פערי ידע בין חוקרים מומחים לקהל הרחב (תוך כדי קריאת המסמכים הקיימים וקוד המקור) → שבוע-שבועיים יצירה של מסמכי עזר ושינוי מבנה שלהם כדי לגשר על הפער הזה → 3 שבועות כתיבה של מסמכי עזר מפורטים יותר של Dynamic Python Bindings → 3 שבועות הטמעת מדריכים ל-Dynamic Python Bindings → 3 שבועות הטמעת מדריכים ל-ROOT 7 → 4 שבועות יצירה של מפרטים טכניים מפורטים ל-RNTuple → 3 שבועות בדיקה שהיעדים של הפרויקט הושלמו בהצלחה → שבוע
פריטי תוכן והנחיות להצלחה: מסמכי תיעוד מאוחדים למשתמשים ללא פערים תיעוד מלא של המשתמשים עודכן באופן מלא כדי לשקף את התכונות העדכניות ביותר, כלומר כיתות נגזרות חדשות מדריכים למשתמשים באמצעות notebooks של Jupyter