דוח מקרה לדוגמה לשנת 2021

הערה: בדוח הזה מוצג סיכום של נתונים מהבקשות המקוריות לתוכנית וממחקרי המקרה הסופיים של הארגונים. אפשר למצוא קישורים למקרים המלאים לדוגמה בדף התוצאות של Season of Docs 2021.

מידע על Season of Docs

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 בתפקיד בתשלום

נתונים עיקריים לשנת 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, בקשת התקציב הממוצעת הייתה 36,700 ש"ח והחציון היה 36,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' כדי לספק הדרכה וליווי.
• כדאי להקצות יותר זמן מהצפוי להדרכת הכותבים הטכניים, לענות על שאלות ולספק תמיכה במהלך התוכנית, במיוחד אם לכותב הטכני אין ניסיון קודם בתחום של הפרויקט.
• כדאי לתעד את תהליך הגיוס, הקבלה וההדרכה של העובדים כדי להשתמש בו בפרויקטים עתידיים.

(הערה: לא בכל הפרויקטים שצוינו בדוגמאות למקרים הם גייסו את המועמדים לכתיבה טכנית).

בעיות נפוצות בעבודה עם סופרים טכניים

בחלק מהפרויקטים, כותבים טכניים נאלצו לפרוש בגלל נגיף הקורונה או מחלות אחרות, או בגלל אחריות משפחתית שקשורה למגפה. בחלק מהפרויקטים דווחו בעיות תקשורת שקשורות לחוסר התאמה בין אזורי הזמן או לבעיות בחיבור לאינטרנט.

בפרויקטים רבים הבינו שהם העריכו בחסר את הקשיים הכרוכים בהצטרפות לקהילות או בהגדרת כלי העבודה של מסמכי הפרויקט.

בחלק מהפרויקטים היו עיכובים בתשלום לכותבים הטכניים בגלל בעיות בנקאיות ב-Open Collective או בגלל הגבלות תשלום במדינות המגורים של הכותבים.

המסמכים של התוכנית בנושא עמלות של Open Collective לא היו ברורים: Google כיסתה את עמלות העסקאות של Open Collective בהעברה הראשונית של הכספים לפרויקטים, אבל לא עמלות עסקאות שהוחלו על ידי ערוצי תשלום אחרים (כמו עמלות המרה של מטבעות). נשתדל להבהיר את הנושא הזה במסמכי העזרה של תוכניות עתידיות.

סקרים עוקבים

כחלק מתוכנית 'עונת המסמכים', ביקשנו מהפרויקטים להשתתף בסקרים עוקבים. שלחנו שלושה סקרים במאי, באוגוסט ובנובמבר 2022.

בסקר המעקב, ביקשנו מהפרויקטים לאשר שהקישורים להצעה ולמחקר המקרה שלהם עדיין פעילים. הסקר כלל גם שאלות לגבי ההצלחה של הפרויקטים (לפי המדדים שהגדירו בניתוח המקרה) ועל ההשתתפות והתגמול המתמשכים של הכותבים הטכניים בפרויקטים:

1. האם אתם עדיין עובדים עם הסופר הטכני שלכם מ-Season of Docs?

1. אם הסופר הטכני עדיין עובד על הפרויקט שלך, האם הוא מקבל תגמול כלשהו?

1. בשלב הזה, האם לדעתך פרויקט התיעוד שלך מוצלח?

שאלות עתידיות

כמו תמיד, ככל שאנחנו לומדים יותר על תיעוד בקוד פתוח, אנחנו רוצים ללמוד עוד. בעונות הבאות, אנחנו מקווים ללמוד:

• אם יש מתאם בין דומיינים של פרויקטים לבין בחירת doctype או בחירת מדד
• אילו שיטות של גיוס ופתיחת חשבון של סופרים טכניים הן היעילות ביותר להשלמת פרויקטים ולשימור של סופרים טכניים
• לוחות זמנים סבירים למדידת היעילות של המסמכים

יש לנו הרבה שאלות שאנחנו רוצים לבדוק, אבל אנחנו גם רוצים לכבד את הזמן של האדמינים והמנהלים של פרויקטים בקוד פתוח שמשתתפים ב-Season of Docs. העדיפות העליונה של התוכנית היא לתמוך בפרויקטים בפתרון בעיות שקשורות לתיעוד.