Season of Docs היא תוכנית קיימות שמנוהלת על ידי המשרד של Google לתוכניות קוד פתוח. המטרות של Season of Docs הן:
- מתן תמיכה לפרויקטים של קוד פתוח כדי לפתור בעיות בפרויקט באמצעות תיעוד
- לתת לכותבים טכניים הזדמנויות לצבור ניסיון בקוד פתוח
- הגברת המודעות לקוד פתוח, לתיעוד ולכתיבה טכנית
- איסוף ושיתוף מידע על מדדים יעילים בתיעוד של קוד פתוח
מידע נוסף על Season of Docs זמין באתר התוכנית.
סקירה כללית על התוכנית לשנת 2022
איך פועל Season of Docs
במסגרת Season of Docs, ארגונים שולחים הצעת פרויקט כדי להגיש בקשה להשתתפות. הצעת הפרויקט כוללת:
- מידע על הארגון
- תיאור של הבעיה שהפרויקט מתמודד איתה
- איך הפרויקט ישתמש בתיעוד כדי לפתור את הבעיה
- איך הפרויקט ימדוד את האפקטיביות של התיעוד (מדדים)
- ציר זמן של העבודה
- תקציב פרויקט
- כל מידע נוסף, כמו הניסיון של הארגון בתוכניות דומות, או כל דבר אחר שיעזור לאדמינים של Season of Docs להבין את הפרויקט והבעיה
אחרי שהארגונים מתקבלים לתוכנית, הם מגייסים ומעסיקים ישירות את הכותבים הטכניים שלהם. במסגרת Season of Docs, נעשה שימוש ב-Open Collective כדי לממן את הארגונים, והארגונים משלמים לכותבים הטכניים דרך Open Collective. התקציבים והתשלומים לפרויקטים שקופים. התקציבים מופיעים בהצעות לפרויקטים של הארגון שזמינות באתר Season of Docs, והתשלומים מופיעים בחשבון Open Collective של Season of Docs.
ארגונים נחשבים כמי שהשלימו בהצלחה את התוכנית כשהם שולחים את דוח המחקר שלהם. בנוסף, הארגונים מתבקשים להשלים הערכות חודשיות במהלך התוכנית ושלושה סקרי מעקב רבעוניים במהלך השנה שלאחר סיום התוכנית.
רגעים מרכזיים מ-2022
"אחרי פרסום המסמך החדש, מספר הביקורים היומיים ב-Casbin וב-Casdoor כמעט הוכפל, ושיעורי הנטישה ירדו בכ-30%". – Casbin
"אחד הדברים הכי טובים שקרו בעקבות הפרויקט הזה הוא לראות את [הכותבים הטכניים שלנו] מתקדמים לתפקידי מנהיגות בקהילה שלנו. שני התורמים האלה מובילים עכשיו את הפגישות של קבוצת העבודה והקהילה, וגם תורמים לעיצוב ולתחזוקה של הפרויקטים שלנו". —moja-global
[GSoD] עזר לנו לגייס שני כותבים טכניים מוכשרים, וזה מאוד קשה בדרך כלל. הם ממשיכים לתרום באופן פעיל ל-OpenMined, והייתה לנו חוויית עבודה נהדרת איתם". – OpenMined
"בנוסף, המדריך החדש הרבה יותר קל למתחילים בתחום של ספקטרומטריית מסה חישובית. כדי להמחיש את הנקודה הזו: המענק של CZI מספק גם מלגות לאנשים שהיו בעבר במצב סוציו-אקונומי נמוך, וחלק מהזוכים השתמשו במדריך החדש של OpenMS כדי להתחיל את תקופת ההתמחות שלהם שנמשכת שישה שבועות, ונתנו ביקורות חיוביות על המדריך החדש". – OpenMS
נתוני סיכום לשנת 2022
בשנת 2022, תוכנית Season of Docs קיבלה 31 פרויקטים מתוך 67 בקשות, ו-30 פרויקטים השלימו את התוכנית בהצלחה. מתוך 31 הארגונים שהתקבלו, 17 ארגונים הגישו בקשה חוזרת.
ב-31 הפרויקטים שאושרו הועסקו 58 כותבים טכניים. יותר מ-190 כותבים טכניים הביעו עניין בהשתתפות בתוכנית והוסיפו את הפרטים שלהם ליצירת קשר וקישורים לתיקי העבודות שלהם במאגר GitHub של Season of Docs.
בתוכנית של 2022:
- 100% מהארגונים דיווחו על חוויה חיובית בתהליך הגשת הבקשה
- 100% מהארגונים דיווחו על חוויה חיובית עם התיעוד או התוכן באתר התוכנית
- 93% מהארגונים דיווחו על חוויה חיובית עם התוכנית
- 90% מהארגונים דיווחו על הצלחה בפרויקט התיעוד שלהם
מידע על הארגונים
הארגונים שהשתתפו ב-Season of Docs בשנת 2022 ייצגו מגוון רחב של פרויקטים של קוד פתוח. קבוצת 2022 כללה:
- כלי פיתוח, כמו AsyncAPI ו-SpyderIDE
- שפות תכנות ומסגרות, כמו Julia, LFortran, R ו-p5.js
- פרויקטים מדעיים, כמו CERN-HSF ו-SymPy
- אפליקציות למשתמשי קצה, כמו Mautic, Open Food Facts, Talawa ו-Ushahidi
- פרויקטים של חומרה ורובוטיקה, כמו ExpressLRS ו-Open-RMF
- פרויקטים של נתונים, כמו GeomScale, GeomStats, OpenMined ו-Weaviate
- פרויקטים של ענן ותשתית, כמו cert-manager, NimbleEdge ו-Cilium
לא אספנו מטא-נתונים על הפרויקטים (כמו תאריך ההקמה, הפיזור הגיאוגרפי של התורמים, מספר התורמים או גודל בסיס המשתמשים).
ביקשנו מהפרויקטים לציין באיזה רישיון קוד פתוח הם משתמשים.
מידע על פרויקטים של תיעוד
בעיות במסמכים
הבעיות העיקריות שהארגונים קיוו לפתור באמצעות תיעוד בתוכנית של שנת 2022 כללו:
שימו לב: ארגונים יכולים לדווח על כמה בעיות בתיעוד. לפרטים נוספים, אפשר לעיין בדף התוצאות של Season of Docs 2022, שכולל קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
סוגי המסמכים שנוצרו
מסמכי הדרכה היו סוג התיעוד שהוזכר הכי הרבה במקרי השימוש משנת 2022.
סוגי מסמכים אחרים שהוזכרו במקרי השימוש כוללים:
- מדריך למתחילים
- מילון מונחים
- שאלות נפוצות
- מאגר ידע
- רכיבים
- תוכן בבלוג או ברשתות חברתיות
- מדריך למנהלי פרויקטים
חלק מהקטגוריות האלה לא מוגדרות באופן חד-משמעי, ופרויקט תיעוד יחיד יכול להכיל כמה סוגים או תכונות של תיעוד.
לפרטים נוספים, אפשר לעיין בדף התוצאות של Season of Docs 2022, שכולל קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
תקציבים
בקשת התקציב הממוצעת הייתה 11,679 $והחציון היה 12,150$. חמישה ארגונים ביקשו וקיבלו את המענק הגבוה ביותר שזמין (15,000$), ושלושה ארגונים ביקשו את המענק הנמוך ביותר (בין 5,000 $ל-7,000$).
המדדים
בפרויקטים שמתוארים במקרי השימוש, מפורטים המדדים שבהם השתמשו כדי לאמוד את הצלחת פרויקטי התיעוד.
המדדים המוצעים המובילים היו:
מדדים מוצעים אחרים כללו:
- בקשות משיכה/תרומות נוספות לתיעוד
- משוב ישיר יותר בדפי תיעוד
- זמן השהייה בדף
- בעיות שהועלו (כאינדיקטור לשימוש)
- משתתפים בפורומים
- מספר השותפים/המתנדבים/השילובים
- שיעור עזיבה מופחת
- הגברת המוּדעוּת בקהילה.
בגלל חלון הזמן הקצר בין סיום פרויקטי הכתיבה הטכנית לבין שליחת מחקרי המקרה, רוב המשתתפים בקבוצה של 2022 לא הצליחו לאסוף מספיק נתונים בזמן שליחת מחקרי המקרה כדי לקבוע אם הם עמדו במדדים הראשוניים או לא.
ככל שנקבל תשובות לסקרים למעקב בשנת 2023, נעדכן את הדוח הזה כדי להוסיף מידע על הפרויקטים שהשיגו את המדדים שלהם או עדכנו את המדדים שלהם.
לפרטים נוספים, אפשר לעיין בדף התוצאות של Season of Docs 2022, שכולל קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
עבודה עם כותבים טכניים
בתוכנית Season of Docs, הפרויקטים צפויים לגייס, לראיין, להעסיק ולשלם לכותבים טכניים ישירות. כותבים טכניים יכולים להוסיף את עצמם למאגר המידע שמנוהל על ידי Season of Docs במאגר GitHub שלנו, אבל צוות Season of Docs לא בודק או ממליץ על כותבים טכניים.
שיטות מומלצות לשכירת כותבים טכניים לפרויקטים של קוד פתוח
ביקשנו מהפרויקטים לשתף את השיטות המומלצות שלהם לגיוס, להעסקה ולעבודה עם כותבים טכניים. ההמלצות המובילות היו:
גיוס
- לראיין פחות מועמדים, ולהשתמש בסשן תרגול בזמן אמת, במקום רק לבדוק קורות חיים
- מיומנויות תקשורת כתובה ובעל פה חשובות יותר משליטה בשפה או בכלים של הפרויקט
- לשאול שאלות ישירות לגבי האופן שבו הכותב הטכני ירכוש את הידע הדרוש בתחום כדי לעבוד על הפרויקט
- אם מישהו מתלהב מהמשימה של הפרויקט שלכם וחולק את ערכי הליבה של קוד פתוח, סביר יותר שהוא יישאר בעל מוטיבציה לאורך כל הפרויקט
- כדאי להיות פתוחים להצעות ממועמדים מכל העולם, כי מגוון של נקודות מבט ורקעים יעזור לפרויקט שלכם. עם זאת, חשוב לזכור שאם הכותבים והמנטורים נמצאים ביותר מדי אזורי זמן שונים, יכול להיות שתידרש השקעה רבה כדי לשמור על תקשורת טובה.
משרות פתוחות
- להשתמש בחוזה שמפרט בבירור את התוצרים, את לוחות הזמנים לתשלומים ואת ההתחייבויות הספציפיות לזמנים
- אם יש הרבה נתונים לא ידועים בפרויקט, כדאי לכלול אבן דרך לגילוי או למחקר בנפרד מיצירת התיעוד
תיאום ותקשורת
- כדאי לנהל יומן פגישות שבו מתעדים את ההחלטות שהתקבלו, כדי שכל מי שעובד על הפרויקט יוכל להבין את ההקשר ואת השלבים הבאים
- חשוב להבהיר מה מצופה מהתקשורת ומה התדירות שלה, בין אם מדובר בשיחות שבועיות, באימיילים יומיים או בעדכוני סטטוס בערוץ צ'אט
- להגיב במהירות ולתת משוב ברור שכולל את ה'למה' ולא רק את ה'מה'
- כדאי לקשר את הכותבים הטכניים לקהילה הרחבה יותר כדי לתת להם הקשר ולשתף את העבודה שלהם
תהליכים וכלים
- ליצור תהליך תיעוד שיימשך גם אחרי תוכנית Season of Docs, ושהקהילה כולה תוכל לתרום לו
- בדיקת המסמכים תימשך לפחות כמו סקר קוד, והיא תהיה אינטנסיבית באותה מידה. חשוב להקצות מספיק זמן לבדיקה.
חלק מההמלצות נערכו וצומצמו לשם הבהרה.
בדומה לתוכנית של 2021, רוב הכותבים הטכניים ב-Season of Docs 2022 הגישו בקשות ישירות לארגונים שעבדו איתם.
בעיות נפוצות בעבודה עם כותבים טכניים
בתוכנית של 2022, פחות פרויקטים דיווחו על בעיות בעבודה עם הכותבים הטכניים שלהם. הבעיה הכי גדולה הייתה שכותבים טכניים לא הצליחו להשלים את התוכנית, בגלל מחלה, קבלת עבודה במשרה מלאה או חוסר יכולת לעמוד בהתחייבות הזמן.
בפרויקט אחד דווח שהפרויקט לתיעוד היה תלוי בעבודה שבוצעה כחלק מGoogle Summer of Code, ושהיה קשה לנהל את התלות הזו. בפרויקט אחר נתקלו בקשיים כשמשרד הביטחון במדינה של הכותב הטכני החרימו את החומרה שהוא היה צריך לתעד, ולא הייתה אפשרות לייבא אותה.
סקרים למעקב
שלושה סקרים למעקב יישלחו למשתתפים בשנת 2022 במאי, באוגוסט ובנובמבר 2023. התוצאות יפורסמו בקטע הזה כשהן יתקבלו.
שאלות עתידיות
כמו תמיד, ככל שאנחנו לומדים יותר על תיעוד בקוד פתוח, כך אנחנו רוצים ללמוד עוד!
בעונות הבאות אנחנו מקווים:
- איסוף של עוד מטא-נתונים של פרויקטים כדי לחפש קורלציות בין גיל הפרויקט, גודל הקהילה או השפה לבין צורכי התיעוד
- ניתוח פרויקטים של תיעוד כדי לבדוק אם אפשר להכליל אותם בתבניות שניתנות לשיתוף
- פיתוח קריטריון הערכה לראיון של כותבים טכניים בפרויקטים של קוד פתוח
יש הרבה שאלות שהיינו רוצים לבדוק, אבל חשוב לנו גם לכבד את הזמן של האדמינים והמפתחים של פרויקטים בקוד פתוח שמשתתפים ב-Season of Docs. התכנית מתמקדת בעיקר בתמיכה בפרויקטים בפתרון בעיות באמצעות תיעוד.