השלב הנוכחי:
תוכנית Docs לעונה של 2021 הסתיימה ב-14 בדצמבר 2021. להסבר על ציר הזמן
מידע על העונה של Docs
עונה של Docs היא תוכנית קיימוּת המנוהלת על ידי המשרד לתוכניות קוד פתוח של Google. המטרות של עונת Docs הן:
- מתן תמיכה לפרויקטים של קוד פתוח כדי לפתור בעיות בפרויקטים בעזרת תיעוד
- מתן הזדמנויות לכותבים טכניים לצבור ניסיון בקוד פתוח
- העלאת המודעות לקוד פתוח, לתיעוד ולכתיבה טכנית
- איסוף ושיתוף מידע על מדדים יעילים במסמכי תיעוד של קוד פתוח
מידע נוסף על העונה של Docs זמין באתר התוכנית.
סקירה כללית של התוכנית לשנת 2021
שינויים בתוכנית בשנת 2021
בשנים 2019 ו-2020, ארגונים וכותבים טכניים ביקשו בנפרד גישה לעונה של תוכנית Docs, והכותבים הטכניים הותאמו עם הארגונים לפי עונת מנהלי התוכנית של Docs. ארגונים סיפקו חונכים לעבוד עם הכותבים הטכניים שקיבלו מלגה על עבודתם, בהתאם למיקום שלהם. בתוכנית בדקו אם הכותבים הטכניים, החונכים והאדמינים של הארגון היו מרוצים מהשתתפותם בתוכנית, אבל לא מדדו את תוצאות התיעוד.
בשנת 2021, הצוות של 'עונת המסמכים של Google' ביצע שינויים משמעותיים בתוכנית כדי להתמקד במדידת תוצאות המסמכים ובאפשרות של גמישות רבה יותר לארגונים ולכותבים הטכניים.
- ארגונים שמופעלים עם הצעות לפרויקטים, כולל תקציב ומדדים מוצעים
- כותבים טכניים כבר לא החלו להגיש בקשה דרך Google כדי להתאים לארגונים, אלא ישירות על הארגונים שהתקבלו
- ארגונים שהתקבלו קיבלו מענקים דרך Open Collective, שבאמצעותם שילמו לכותבים טכניים
- ארגונים קבעו תגמול לכותבים הטכניים
- ארגונים שלחו הערכות סופיות, מקרים לדוגמה וסקרי מעקב שנענו
ממצאים כלליים לשנת 2021
ארגונים
- השינויים בתוכנית של 2021 הובילו לירידה של 30% במספר ארגונים שהוגשו בשנת 2021 לעומת 2020, אבל האדמינים של הארגון בשנת 2021 היו מרוצים יותר מהתוכנית בשנת 2020 (93% לעומת 91%)
בעיות, doctypes ומדדים
- רוב הפרויקטים התמקדו ביצירת מסמכים להפחתת נטל התחזוקה (על ידי צמצום בעיות/שאלות) ו/או הגדלת ההשתתפות בפרויקט (על ידי משתמשים בפרויקט או על ידי תורמי תוכן).
- 50% מהארגונים המותרים יצרו תוכן של 'מדריך' או 'הדרכה'.
- יותר מ-50% מהארגונים שהתקבלו חשבו שהמסמכים הנוכחיים שלהם חסרים, לא מאורגנים או מיושנים.
- באופן כללי, הפרויקטים רצו למדוד את יעילות התיעוד שלהם באמצעות אינטראקציות, במיוחד פחות בעיות שהועלו ויותר מבקרים במסמכים והשתתפות בפרויקטים.
- נכון לנובמבר 2022, 25 מתוך 30 פרויקטים הגיבו:
- 18 פרויקטים אמרו שהם עמדו במדדים המקוריים שלהם
- 5 פרויקטים עמדו במדדים המתוקנים
- שני פרויקטים אמרו שעדיין מוקדם מדי לדעת
השתתפות בתוכנית
- גיוס, גיוס ותשלום של כותבים טכניים בתשלום היה החלק הקשה ביותר בתוכנית עבור מנהלי ארגונים.
- נכון לנובמבר 2022, 24 מתוך 30 ארגונים מגיבים:
- 18 ארגונים עדיין עבדו עם הכותבים הטכניים של עונת ה-Docs (כשותפים פעילים נוספים או כמקור לקבל תשובות לשאלות)
- 4 ארגונים עבדו עם תפקיד בתשלום של הכותבים הטכניים בעונת ה-Docs
- 18 ארגונים עדיין עבדו עם הכותבים הטכניים של עונת ה-Docs (כשותפים פעילים נוספים או כמקור לקבל תשובות לשאלות)
המיטב של 2021
- מספר פרויקטים ציינו שהכותב הטכני התכוון להמשיך לעבוד על הפרויקט אחרי סיום העונה של תוכנית Docs
- ב-Metanorma היו כל כך הרבה כותבים טכניים, שהצליחו למצוא מימון מתאים כדי להעסיק כותב נוסף שיעבוד לצד הכותב בתמיכה ב-Docs במהלך התוכנית
- Moja Global מצאה שהקהילה הייתה מעורבת מאוד בתיעוד והקים קבוצת עבודה חדשה לתיעוד כדי לאפשר לתורמים נוספים להשתתף במסמכי הפרויקט.
נתוני סיכום לשנת 2021
בשנת 2021 התקבלו לתוכנית 82 ארגונים ו-30 ארגונים של קוד פתוח. (הקריטריונים של הבחירה מפורטים במדריך ליצירת אפליקציות). ניתן למצוא את הרשימה המלאה של הארגונים המשתתפים באתר של עונה של Docs. כל 30 הארגונים שהתקבלו הגישו את דוח המקרה הסופי כדי להשלים את השתתפותם בתוכנית 2021.
מידע על הארגונים
הארגונים שמשתתפים בעונת Docs 2021 מייצגים מגוון רחב של פרויקטים בקוד פתוח. הקבוצה בעלת המאפיינים המשותפים בשנת 2021 כללה:
- פרויקטי שפה גדולים כמו Julia, Perl ו-R
- פרויקטים בחינוך, אקלים, פינטק, בריאות, שירותי ספרייה, למידת מכונה, ספקטרומטריית המונים, חוזים ציבוריים ורובוטיקה
- פרויקטים ממוקדי מפתחים, כולל כלי כאוס בהנדסת תוכנה, fuzzers, ערכות SDK של Chatbot, צינורות ניתוח הרכבה של תוכנה, כלים למעקב אחר ביצועים וכלי תכנות חזותי
- פרויקטים של תיעוד לכלי תיעוד, כמו Redocly ו-Metanorma
פרויקטים של מערכות אקולוגיות של Python היו קטגוריית המשנה הגדולה ביותר. הקבוצה בעלת המאפיינים המשותפים של שנת 2021 כללה את ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite ו-SymPy.
לא אספנו מטא-נתונים לגבי הפרויקטים (כמו תאריך הקמה, התפלגות גיאוגרפית של תורמים, מספר השותפים או גודל בסיס המשתמשים).
עם זאת, ביקשנו מפרויקטים לציין באיזה רישיון קוד פתוח הם משתמשים.
הבעיות בתיעוד שתיארנו על ידי הארגונים משנת 2021 הן בעיות נפוצות מאוד בפרויקטים של קוד פתוח ובתיעוד טכני באופן כללי.
הבעיות העיקריות שארגונים קיוו לפתור בתוכנית לשנת 2021 כללו:
חשוב לציין שארגונים יכולים לדווח על כמה בעיות במסמכים. לקבלת פרטים נוספים, אפשר לעיין בדף התוצאות של עונה של Docs 2021, שמכיל קישור למקרים לדוגמה המלאים של כל ארגון.
סוגי התיעוד שנוצרו
מדריכים היו סוג התיעוד שנזכר הכי הרבה במקרים לדוגמה בשנת 2021.
סוגי תיעוד אחרים המוזכרים במקרים לדוגמה כללו צינור עיבוד נתונים של מסמכים כקוד, תרשים, מילון מונחים, מדריך סגנון, שאלות נפוצות, בינאום, Codelab, מודל תוכן, מודולים, תיעוד קונספט, הודעות שגיאה, מחקרי משתמשים, Readme, מאגר ידע.
חלק מהקטגוריות האלה מעורפלות, ופרויקט תיעוד יחיד יכול להכיל מספר סוגי תיעוד או תכונות.
מספר פרויקטים שיש הפניה אליהם ספציפית באמצעות DiátAM framework כמדריך לתכנון סוגי המסמכים שלהם.
לקבלת פרטים נוספים, אפשר לעיין בדף התוצאות של עונה של Docs 2021, שמכיל קישור למקרים לדוגמה המלאים של כל ארגון.
תקציבים
בשנת 2021, בקשת התקציב הממוצעת הייתה $10,200 והחציון היה $10,000. רק שלושה ארגונים ביקשו וקיבלו את המענק המקסימלי האפשרי (15,000$) ושלושה ארגונים נוספים ביקשו את המענק הנמוך ביותר האפשרי (5,000$).
המדדים
בפרויקטים שתוארו במקרים לדוגמה שלהם, המדדים שהם השתמשו בהם כדי להעריך את הצלחת פרויקטי התיעוד שלהם.
המדדים שהוצעו הכי הרבה היו:
מדדים מוצעים אחרים כללו כוכבים של GitHub, משך השהייה בדף, המרות ברשימות דיוור, בדיקות משתמשים איכותיות, מספר המשתתפים בפורומים, מספר השותפים/מתנדבים/שילובים.
בגלל החלון הקצר בין סיום הפרויקטים הטכניים של הכתיבה לבין שליחת המקרים לדוגמה, רוב הקבוצה בעלת המאפיינים המשותפים בשנת 2021 לא הצליחה לאסוף מספיק נתונים כדי לקבוע אם המדדים הראשוניים התקיימו או לא.
לקבלת פרטים נוספים, אפשר לעיין בדף התוצאות של עונה של Docs 2021, שמכיל קישור למקרים לדוגמה המלאים של כל ארגון.
עבודה עם כותבים טכניים
השינוי הגדול ביותר בעונה של תוכנית Docs בשנת 2021 כלל את האופן שבו פרויקטים עבדו עם כותבים טכניים. בעונות קודמות, כותבים טכניים פנו ישירות ל-Google, ומנהלי התוכנית קיבלו מלגת זכאות ישירות מ-Google.
בשנת 2021, כותבים טכניים פנו ישירות לפרויקטים והפרויקטים הגדירו את התקציב לפיצויים של כותבים טכניים, באמצעות התשלומים שבוצעו דרך קרן קולקטיבית של Open בעונה של Docs.
לרוב הפרויקטים שמשתתפים בתוכנית של שנת 2021 היה ניסיון מועט, אם בכלל, בגיוס או בגיוס של כותבים טכניים. בפרויקטים רבים צוין שהשלב הזה בתהליך ככזה שזקוק לתמיכה נוספת. בתגובה למשוב הזה, צוות 'עונה של Docs' הוסיף למדריך התוכנית מסמכים ליצירת הסכמי כתיבה טכניים.
המלצות לגיוס עובדים
הפרויקטים התבקשו לתת המלצות לפרויקטים אחרים שמעוניינים להשתתף בעונה של Docs. ההמלצות המובילות לגיוס היו:
- שתפו את חומרי הגיוס של כותבים טכניים בהקדם האפשרי, עוד לפני שהתקבלתם לתוכנית. בקשו מהקהילה שלכם להפנות מועמדים אפשריים.
- שיתוף עם גורמים מחוץ לערוצי הפרויקט. להשתמש בשפה שמעודדת את קבלת האחר ולעודד ישירות מועמדים מרקעים שסובלים מחוסר ייצוג בבקשה להגיש בקשה.
- מבינים אילו כלים חיוניים לתהליך יצירת המסמכים ולגייס כותבים טכניים עם ניסיון בשימוש בכלים האלה.
- צרו ציפיות ברורות עבור הכותב הטכני לגבי משלוחים ואבני דרך, ערוצי תקשורת וביצוע צ'ק-אין, ותהליכי תשלום ותזמון.
- נסו להשקיע בחברי הקהילה ולסייע להם לצמוח ככותבים טכניים על ידי שימוש בכותב הטכני ב-עונה של Docs למתן חונכות והדרכה.
- כדאי להשקיע יותר זמן מהצפוי לקליטת כותבי תוכן טכניים, למענה על שאלות ולמתן תמיכה במהלך התוכנית, במיוחד אם לכותב הטכני אין ניסיון קודם בדומיין של הפרויקט שלכם.
- מתעדים את תהליך הגיוס, ההעסקה והקליטה של עובדים שתוכלו להשתמש בהם בפרויקטים עתידיים.
(הערה: לא כל הפרויקטים שמצוינים בתיאורי המקרה שלהם גייסו את המועמדים לכותבים הטכניים).
בעיות נפוצות בעבודה עם כותבים טכניים
כותבים טכניים במספר פרויקטים נאלצו לפרוש עקב נגיף הקורונה או מחלות אחרות, או בגלל אחריות משפחתית שקשורה למגיפה. חלק מהפרויקטים דיווחו על בעיות תקשורת שקשורות לחוסר התאמה באזורי זמן או לבעיות בחיבור לאינטרנט.
בפרויקטים גילו שהם לא העריכו את הקשיים הכרוכים בהצטרפות לקהילות או בהגדרת שרשרת הכלים של המסמכים של הפרויקט.
בחלק מהפרויקטים היו עיכובים בתשלום לכותבים הטכניים בגלל בעיות בנקאיות ב-Open Collective או בגלל שבמדינות המגורים של הסופרים היו הגבלות על התשלום.
מסמכי התוכנית בנושא עמלות Open Collective לא היו ברורים: Google כיסה את עמלות העסקה של Open Collective עבור ההעברה הראשונית של כספים לפרויקטים, אך לא את עמלות העסקאות שנגבו על ידי ערוצי תשלום אחרים (כמו עמלות המרת מטבעות). נפעל כדי להבהיר זאת יותר בתיעוד של תוכניות עתידיות.
סקרים למעקב
במסגרת העונה של תוכנית Docs, פרויקטים התבקשו להשתתף בסקרים המשך. 3 סקרים נשלחו במאי, אוגוסט ונובמבר 2022.
בסקר העוקב התבקשו על ידי הפרויקטים לאשר שהקישורים להצעה ולמקרה לדוגמה שלהם עדיין פעילים. הסקר כלל גם שאלות לגבי הצלחת הפרויקטים שלהם (כפי שנקבע על ידי המדדים שהם הגדירו במקרה לדוגמה) וההשתתפות והתגמול של הכותבים הטכניים בפרויקט:
- עדיין עובדים עם הכותב הטכני של עונה של Docs?
- אם הכותב הטכני עדיין עובד על הפרויקט, האם הוא מקבל תגמול כלשהו?
- בשלב הזה, לדעתכם פרויקט התיעוד שלכם מוצלח?
שאלות עתידיות
כמו תמיד, ככל שנלמד יותר על תיעוד בקוד פתוח, כך נוכל ללמוד יותר! בעונות הבאות, אנחנו מקווים ללמוד:
- האם דומיינים של פרויקטים תואמים לבחירת doctype או לבחירת מדד
- אילו שיטות לגיוס ולקליטה של כותבים טכניים הן היעילות ביותר להשלמת פרויקטים ולשימור עובדים טכניים
- לוחות זמנים סבירים למדידת היעילות של מסמכים
יש שאלות רבות שהיינו רוצים לחקור, אבל אנחנו גם רוצים לכבד את זמנם של המנהלים והמנהלים של פרויקט הקוד הפתוח שמשתתפים בעונת Docs. בראש סדר העדיפויות של התוכנית יש תמיכה בפרויקטים בפתרון הבעיות שלהם באמצעות תיעוד.