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