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