השלב הנוכחי:
המקרים לדוגמה פורסמו. ציר הזמן
Season of Docs היא תוכנית קיימות שמנוהלת על ידי המשרד לתוכניות קוד פתוח של Google. היעדים של Season of Docs הם:
- מתן תמיכה בפרויקטים בקוד פתוח כדי לפתור בעיות בפרויקט באמצעות מסמכי תיעוד
- לתת לכותבים טכניים הזדמנויות לצבור ניסיון בקוד פתוח
- הגברת המודעוּת לקוד פתוח, למסמכי עזרה ולכתיבה טכנית
- איסוף ושיתוף מידע על מדדים אפקטיביים במסמכי תיעוד בקוד פתוח
מידע נוסף על 'עונת התיעוד' זמין באתר של התוכנית.
סקירה כללית של התוכנית לשנת 2022
איך פועל Season of Docs
כדי להשתתף ב-Season of Docs, ארגונים שולחים הצעת פרויקט. הצעת הפרויקט כוללת:
- מידע על הארגון
- תיאור הבעיה שבה הפרויקט נתקל
- איך התיעוד ישמש את הפרויקט לפתרון הבעיה
- איך יתבצע במסגרת הפרויקט מדידת היעילות של המסמכים (מדדים)
- ציר זמן של העבודה
- תקציב פרויקט
- מידע נוסף, כמו הניסיון של הארגון בתוכניות דומות או כל דבר אחר שיעזור למנהלי Season of Docs להבין את הפרויקט והבעיה
אחרי שהארגונים יקבלו אישור להצטרף לתוכנית, הם יגייסו וישכרו את הכותבים הטכניים שלהם ישירות. ב-Season of Docs משתמשים ב-Open Collective כדי לממן את הארגונים, והארגונים משלמים לכותבים הטכניים דרך Open Collective. התשלומים והתקציב של הפרויקטים שקופים. התקציב נכלל בהצעות לפרויקטים של הארגון שזמינות באתר של Season of Docs, והתשלומים גלויים בחשבון של Season of Docs ב-Open Collective.
ארגונים נחשבים כמי שהשלימו את התוכנית אחרי שהם שולחים את דוח המחקר. הארגונים גם מתבקשים להשלים הערכות חודשיות במהלך התוכנית ושלושה סקרים למעקב רבעוני במהלך השנה שלאחר סיום התוכנית.
רגעים מיוחדים ב-2022
"אחרי פרסום המסמך החדש, מספר הביקורים היומיים ב-Casbin וב-Casdoor כמעט הוכפל, ושיעורי העזיבה ירדו בכ-30%" – Casbin
"אחד מהתוצאות הטובות של הפרויקט הזה היה לראות את [הכותבים הטכניים שלנו] מתקדמים לתפקידים מובילים בקהילה שלנו. שני התורמים האלה מובילים עכשיו את קבוצת העבודה ואת פגישות הקהילה, וגם תורמים לתכנון ולתחזוקה של הפרויקטים שלנו". —moja-global
"[GSoD] עזר לנו לגייס שני סופרים טכניים מוכשרים, דבר שקשה מאוד לעשות במסגרת רגילה. הם ממשיכים לתרום ל-OpenMined בקוד פתוח, והחוויה שלנו איתם הייתה נהדרת" – OpenMined
"בנוסף, המדריך החדש קל יותר לאנשים שמתחילים לעבוד עם ספקטרומטרית מסה חישובית. כדי להמחיש את הנקודה הזו: המענק של CZI מספק גם מענקים לאנשים שהיו בעבר בעלי חסות, וחלק מהזוכים השתמשו במדריך החדש של OpenMS כדי להתחיל את תקופת ההתמחות שלהם בת שש השבועות, והם נתנו ביקורות חיוביות על המדריך החדש". – OpenMS
נתוני סיכום לשנת 2022
בשנת 2022, 31 פרויקטים אושרו לתוכנית Season of Docs מתוך 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 כללו:
חשוב לזכור שארגונים יכולים לדווח על כמה בעיות במסמכים. מידע נוסף זמין בדף התוצאות של עונת Docs 2022, שבו יש קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
סוגי המסמכים שנוצרים
מסמכי הדרכה היו סוג המסמכים הנפוץ ביותר שצוין בדוגמאות למקרים לדוגמה מ-2022.
סוגי מסמכים נוספים שצוינו בסקירות המקרה:
- מדריך למתחילים
- מילון מונחים
- שאלות נפוצות
- מאגר ידע
- רכיבים
- תוכן בבלוג או ברשתות חברתיות
- מדריך למנהלי תוכנה
חלק מהקטגוריות האלה הן מעורפלות, ופרויקט תיעוד אחד יכול להכיל כמה סוגים או תכונות של תיעוד.
מידע נוסף זמין בדף התוצאות של עונת Docs 2022, שבו יש קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
תקציבים
הבקשה הממוצעת לתקציב הייתה 42,790 ש"ח והחציון היה 44,700 ש"ח. חמישה ארגונים ביקשו והתקבלה להם המענק הגבוה ביותר שזמין (15,000$), ושלושה ביקשו את המענק הנמוך ביותר (בין 5,000 $ל-7,000$).
המדדים
בפרויקטים שמפורטים בסקירות המקרה, הם מתארים את המדדים שבהם השתמשו כדי למדוד את ההצלחה של פרויקטי התיעוד שלהם.
המדדים המובילים שהוצעו היו:
מדדים נוספים שהוצעו:
- בקשות משיכה/תרומות נוספות למסמכי תיעוד
- משוב ישיר יותר על דפי מסמכי התיעוד
- משך הזמן בדף
- בעיות שדווחו (כמדד לשימוש)
- משתתפים בפורומים
- מספר השותפים/המתנדבים/השילובים
- הפחתת שיעור העזיבה
- הגברת המוּדעוּת בקרב הקהילה.
בגלל החלון הקצר שחלף בין סיום פרויקטי כתיבת הטכנית לבין שליחת מקרי המחקר, רוב המשתתפים בתוכנית של שנת 2022 לא הצליחו לאסוף מספיק נתונים בזמן שליחת מקרי המחקר כדי לקבוע אם הם עמדו במדדים הראשוניים או לא.
כשנקבל תשובות לסקרי המעקב ב-2023, נעדכן את הדוח הזה ונוסיף מידע על הפרויקטים שהשיגו את המדדים שלהם או ששינו את המדדים שלהם.
מידע נוסף זמין בדף התוצאות של עונת Docs 2022, שבו יש קישורים להצעות המקוריות לפרויקטים ולמקרים לדוגמה מלאים של כל ארגון.
עבודה עם סופרים טכניים
בתוכנית Season of Docs, הפרויקטים אמורים לגייס, לקיים ראיונות, להעסיק ולשלם לכותבים טכניים ישירות. כותבים טכניים יכולים להוסיף את עצמם לאינדקס שמנוהל על ידי Season of Docs במאגר GitHub שלנו, אבל צוות Season of Docs לא בודק כותבים טכניים או ממליץ עליהם.
שיטות מומלצות לגיוס של כותבים טכניים לפרויקטים בקוד פתוח
ביקשנו מהפרויקטים לשתף את השיטות המומלצות שלהם לגיוס, לקבלה ולעבודה עם סופרים טכניים. ההמלצות המובילות היו:
גיוס
- לנהל פחות ראיונות ולהשתמש בסשן אימון בשידור חי, במקום רק לבדוק קורות חיים
- עדיפות ליכולות תקשורת בכתב ובעל פה על פני מיומנות בשפה או בכלים של הפרויקט
- שואלים שאלות ישירות לגבי האופן שבו הסופר הטכני ירכוש את הידע הנחוץ בתחום כדי לעבוד על הפרויקט שלכם.
- אנשים שמתלהבים מהמטרה של הפרויקט ושחולקים את הערכים הבסיסיים של קוד פתוח צפויים לשמור על המוטיבציה לאורך כל הפרויקט.
- כדאי להיות פתוחים לבקשות של אנשים מכל רחבי העולם, כי מגוון נקודות מבט ורקעים יעזרו לפרויקט שלכם – אבל חשוב לזכור שאם יש לכם סופרים ומנטורים שנמצאים באזורי זמן שונים מדי, יכול להיות שתצטרכו להשקיע הרבה מאמץ כדי לשמור על תקשורת טובה.
משרות פתוחות
- שימוש בחוזה שמפרט בבירור את התוצרים, לוחות הזמנים לתשלומים וההתחייבויות הספציפיות לזמנים
- אם יש בפרויקט הרבה גורמים לא ידועים, כדאי לכלול ציון דרך לגילוי או למחקר בנפרד מהיצירה של המסמכים
תיאום ותקשורת
- כדאי להכין יומן פגישות שבו מתועדות ההחלטות, כדי שיהיה קל יותר לכל מי שעובד על הפרויקט להבין את ההקשר ואת השלבים הבאים.
- חשוב להבהיר מהי התקשורת הצפויה ומה התדירות שלה, בין אם מדובר בשיחות שבועיות, באימיילים יומיים או בעדכוני סטטוס בערוץ צ'אט.
- להיות זמינים ולספק משוב ברור שכולל 'למה' ולא רק 'מה'
- לקשר את הכותבים הטכניים שלכם לקהילה הרחבה יותר כדי לספק להם הקשר ולאפשר להם לשתף את העבודה שלהם
תהליכים וכלים
- ליצור תהליך תיעוד שיימשך מעבר לתוכנית Season of Docs, ושכל הקהילה תוכל לתרום אליו
- בדיקת המסמכים תימשך לפחות זמן רב כמו בדיקת הקוד, ותהיה אינטנסיבית באותה מידה. חשוב להקדיש לכך מספיק זמן.
חלק מההמלצות עברו עריכה וקצרו כדי לשפר את הבהירות שלהן.
בדומה לתוכנית של שנת 2021, רוב הכותבים הטכניים בתוכנית 'עונת ה-Docs' של שנת 2022 הגישו בקשה ישירות לארגונים שבהם הם עבדו.
בעיות נפוצות בעבודה עם סופרים טכניים
בתוכנית של 2022, פחות פרויקטים דיווחו על בעיות בעבודה עם הכותבים הטכניים שלהם. הבעיה העיקרית הייתה שכותבים טכניים לא הצליחו להשלים את התוכנית בגלל מחלה, התחלת עבודה במשרה מלאה או אי-עמידה בהתחייבות לזמן.
בפרויקט אחד דווח שהעבודה על מסמכי התיעוד שלו תלויה בעבודה שמתבצעת במסגרת Google Summer of Code, ושקשה לנהל את יחסי התלות האלה. בפרויקט אחר נתקלו בקשיים כשחומרת המחשב שהכותב הטכני היה צריך לתעד נלקחה על ידי משרד ההגנה במדינה של הכותב, ולא ניתן היה לייבא אותה.
סקרים עוקבים
שלושה סקרים למעקב יישלח למשתתפים מ-2022 במאי, באוגוסט ובנובמבר 2023. נעדכן את הקטע הזה בתוצאות ככל שנקבל אותן.
שאלות עתידיות
כמו תמיד, ככל שאנחנו לומדים יותר על תיעוד בקוד פתוח, אנחנו רוצים ללמוד עוד.
בעונות הבאות אנחנו מקווים:
- איסוף מטא-נתונים נוספים של פרויקטים כדי לבדוק אם יש מתאם בין גיל הפרויקט, גודל הקהילה או השפה לבין הצרכים שלכם לגבי מסמכי התיעוד
- ניתוח פרויקטים של מסמכי עזרה כדי לבדוק אם אפשר להפוך אותם לתבניות שיתופיות
- פיתוח קריטריונים לראיונות עם סופרים טכניים בפרויקטים בקוד פתוח
יש לנו הרבה שאלות שאנחנו רוצים לבדוק, אבל אנחנו גם רוצים לכבד את הזמן של האדמינים והמנהלים של פרויקטים בקוד פתוח שמשתתפים ב-Season of Docs. העדיפות העליונה של התוכנית היא לתמוך בפרויקטים בפתרון בעיות שקשורות לתיעוד.