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