השלב הנוכחי:
התוצאות פורסמו. ציר הזמן
תוכלו להיעזר בדוגמה הזו כדי ליצור דוח מקרה לדוגמה משלכם.
PicklePlus: תיעוד הכלי GloriousPickle לתרומה
ארגון או פרויקט: Glorious Pickle כאן מופיע הקישור לאתר הראשי של הארגון או הפרויקט
תיאור הארגון: GloriousPickle (הגרסה הנוכחית היא 1.2.3, הגרסה הראשונה שוחררה בשנת 2009) היא ספרייה ברישיון MIT שמאפשרת לחשב בקלות את היחס המושלם של מלח, סוכר, חומץ ותבלינים לכל ירק אפשרי לשימור כחמוצים, בכמויות שונות, החל ממלון אחד של מלפפון קטן ועד ספינות מכולות של צנוניות.
מחברים: אופציונלי: רשימת המחברים של ניתוח המקרה. אם נדרש, יש להשתמש בשמות משתמשים
תיאור הבעיה/סיכום ההצעה
איזו בעיה ניסית לפתור באמצעות מסמכים חדשים או משופרים? אם אפשר, מוסיפים קישור לדף ההצעה באתר הפרויקט.
הוספת הרכיבים למסד הנתונים של רכיבי הכלי GloriousPickle כרוכה בזמן רב ומסובך, והכלי לא מכיל תיעוד טוב. לרבים מהאנשים שרוצים לתרום אין ניסיון בשימוש ב-git או בשליחת בקשות משיכה. פירוש הדבר הוא שב-GloriousPickle יש פערים משמעותיים בנתוני הרכיבים שלנו, כך שהכלי שלנו פחות שימושי. אנחנו מקווים ששיפור המסמכים להוספת מרכיבים חדשים יעודד שותפים חדשים לתרום לפרויקט ועוד אנשים ינסו את התהליך.
תיאור הפרויקט
יצירת ההצעה
איך הגעת להצעה שלך ל-Google Season of Docs? איזה תהליך נעשה בארגון כדי לקבל החלטה לגבי רעיון? איך ביקשתם ושילמתם משוב?
קבוצת ה-SIG של GloriousPickle PickleDocs שמחה לשמוע על תוכנית Google Season of Docs דרך ציוץ של המשרד לתוכניות בקוד פתוח של Google. אנשי SIG דיונים על התוכנית בפגישה הדו-שבועיים שלהם, והסכימו ליצור הצעה. שני חברים ב-SIG (@KimChiCook ו- @Dillicious) התנדבו לעבוד על טיוטת ההצעה לבדיקה בפגישה הבאה.
אחרי שה-SIG של PickleDocs הסכים על טיוטת ההצעה, נשלח אימייל לפרויקט הרחב יותר עם בקשה למשוב. 14 חברי קהילה שלחו משוב, כולל @GloriousPicklePat, המנהל של ה-API להוספת מרכיבים. @GloriousPicklePat התנדבה להיות משאב במהלך התוכנית.
אחרי דיון במשוב שקיבלנו ושילוב שלו, ההצעה נשלחה לוועדת הניהול של פרויקט GloriousPickle לצורך הצבעה. כל חמשת חברי GPPSC הצביעו בעד שליחת ההצעה והבקשה, ו-@VinegarViv הסכימה לעזור ליצור את החשבון ב-Open Collective שנדרש כדי להשתתף בתוכנית ולפקח על התשלומים.
תקציב
הוסיפו קטע קצר על התקציב. איך הערכת את העבודה? האם היו הוצאות בלתי צפויות? האם בסופו של דבר הוצאתם פחות מסכום המענק? האם הקצית את הכספים בצורה נכונה, או שחלק מהפריטים שהוקצית להם תקציב היו מיותרים או שהקצית להם יותר או פחות כסף? האם יכולת להשתמש בכספים אחרים מחוץ לעונה של Google Docs?
שני חברים ב-GloriousPickle PickleDocs SIG עבדו ככותבים טכניים (אחד באירופה ואחד בארגנטינה). הם עזרו לנו להעריך את העבודה ולמצוא תקציבים דומים לפרויקטים, על סמך טיוטות של הצעות שהם הכינו בעבר. בנוסף, נשארו לנו 1,000$ממימונם של PicklePals בכנס שלהם ב-2019, והקצינו אותם לפרויקט.
הוצאה בלתי צפויה הייתה עזרה לכותב הטכני שלנו לשכור נקודת Wi-Fi לשיתוף אינטרנט, כי הוא היה באזור שהושפע משריפות יער ואיבד את הגישה לאינטרנט בבית. בנוסף, שלחנו פחות חולצות למשתתפים ממה שתוכנן, כך שההוצאות היו מאוזנות.
בנוסף, החלטנו לשלם ל-@Piccalily, שותפה ב-GloriousPickle (לשעבר עורכת טקסטים מקצועית בחיים הקודמים שלה, לפני שהפכה למלפפון חמוץ) על עזרתה בעריכת הטקסט ובהגהה של המסמכים שנוצרו על ידי הסופר הטכני.
משתתפים
מי עבד על הפרויקט הזה (יש להשתמש בשמות משתמשים אם המשתתפים ביקשו זאת)? איך מצאת את הכותב הטכני שלך ושכרת את שירותיו? איך מצאת מתנדבים או משתתפים בתשלום אחרים? אילו תפקידים היו להם? האם מישהו פרש? מה למדתם על גיוס, תקשורת וניהול פרויקטים?
צוות הליבה שעבד על הפרויקט הזה היה:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (עזרה לאדמינים, GPPSC)
- @BBChips, @GloriousPicklePat (מומחים בנושא)
- Sam Scribe (כותב טכני)
מצאנו את Sam Scribe דרך הרשימה של העונה של Google במאגר GitHub של Docs. חשבנו שהניסיון שלו (סם עבד במגזין קולינרי וגם כתב מסמכי עזרה לאתרים) מתאים לפרויקט שלנו. Sam הצטרף לשיחה הדו-שבועית של קבוצת ה-SIG של PickleDocs ודיבר איתנו על הפרויקט, והציע כמה הצעות חשובות מאוד ששילבנו בהצעה. פנית גם לשני כותבים טכניים נוספים שאנחנו מכירים דרך הרשתות של חברי ה-SIG שלנו, אבל אף אחד מהם לא היה זמין במהלך תקופת התוכנית.
מאחר שרוב חברי קבוצת ה-SIG של PickleDocs נמצאים באזור זמן שחורג רק בכמה שעות מאזור הזמן של סמ, שלחנו קריאה בפורום הדיונים שלנו למשתמשי Pickler שנמצאים באזור הזמן של סמ ומכירים את תהליך הוספת המרכיבים. המשתמש @BBChips התנדב לענות על השאלות של סמ ואף לעזור לו למצוא מומחים אחרים לפי הצורך. בנוסף, @GloriousPicklePat התנדב לעזור ל-Sam להבין את הארכיטקטורה הבסיסית של הכלי ואת הודעות השגיאה האפשריות מה-API, וגם סיפק עזרה בנושא GitHub ו-git.
לצערי, באמצע התוכנית, @VinegarViv נאלצה לפרוש מהפרויקט מסיבות אישיות. חבר GPPSC @GherKen התנדב לענות על שאלות ניהוליות ותשלומים.
אחרי שפספסנו כמה שאלות (ב-GloriousPickle משתמשים במכונה חינמית של Slack, ולפעמים הדיון מתקדם מהר כל כך שאנחנו מפספסים שיחות בגלל מגבלת הארכיון המתחלף), למדנו שצריך לשמור רשימה של השאלות הפתוחות במסמך משותף (השתמשנו במסמך משותף ב-Google Docs). חברי קבוצת ה-SIG של PickleDocs בדקו את השאלות לפני כל פגישה ולוודא שהן מקבלות מענה לפני סיום הפגישה. סער הצליח לפנות ישירות ל- @BBChips לשאלות דחופות.
נהנינו מאוד לעבוד עם Sam, ובנוסף לעדכון המסמכים של GloriousPickle, הוא הפך לחובב מושבע של שימורים.
ציר הזמן
תנו סקירה כללית קצרה של לוח הזמנים של הפרויקט (יש לציין תאריך סיום משוער או אבני דרך ברמת הביניים אם הפרויקט עדיין פעיל).
בזמן שהמתנו לתוכנית של Google Docs להכרזת על הארגונים המשתתפים, חברי PickleDocs SIG חיפשו עבודה קודמת שנראית לנו שתועיל לסאם. במהלך חודש אחד, מצאנו כמה הערות ממאמץ קודם לעדכון המסמכים שהושעה, וגם עבדנו על חלקים מחומרי הביקורת של בשלות המסמכים במאגר opendocs של Google.
אחרי שקיבלנו את החדשות הטובות שנבחרתם ל-Google Season of Docs, סם וה-SIG של PickleDocs נפגשו וקבעו לוח זמנים גס:
| שלב | הושלם על ידי |
|---|---|
| בדיקת הביקורת של המסמכים | 7 במאי |
| תרחישים לדוגמה ביומן חיכוך 3 | 14 במאי |
| בדיקת יומני החיכוך עם @GloriousPicklePat ו- @BBChips, תשובות לשאילתות | 28 במאי |
| טיוטה ראשונה של תרחיש לדוגמה בנושא מסמכים מעודכנים 1 | 25 ביוני |
| טיוטה אחת של תרחיש לדוגמה נבדקה על ידי @GloriousPicklePat ו- @KimChiCook | 2 ביולי |
| טיוטה ראשונה של תרחיש לדוגמה 2 בנושא מסמכים מעודכנים | 2 ביולי |
| טיוטת תרחיש לדוגמה 2 נבדקה על ידי @GloriousPicklePat ו-@Dillicious | 9 ביולי |
| טיוטה ראשונה של תרחיש לדוגמה 3 בנושא מסמכים מעודכנים | 9 ביולי |
| טיוטת תרחיש לדוגמה 3 נבדקה על ידי @Dillicious ו-@KimChiCook | 16 ביולי |
| תשובות לכל השאילתות בכל התרחישים לדוגמה | 30 ביולי |
| רוב חברי קבוצת ה-SIG של PickleDocs היו בחופשה בתאריכים 1-20 באוגוסט | -- |
| התחלת בדיקה של מסמכים חדשים בקהילה (מסמכים שפורסמו כטיוטות באתר GloriousPickle) | 21 באוגוסט |
| משוב מהבדיקה שולב | 10 בספטמבר |
| העתקת מסמכים והגהה שלהם | 17 בספטמבר |
| הסרת הסטטוס 'טיוטה' מהמסמכים, והשקה רשמית של המסמכים | 28 בספטמבר |
| התהליך לעדכון המסמכים שנוצרו | 1 בנובמבר |
| תיאור המקרה הזה נוצר | 8 בנובמבר |
| המקרה לדוגמה נשלח | 16 בנובמבר |
בתקציב ההצעה שלנו, הערכנו שהכותב הטכני ישקיע 10-15 שעות בשבוע בעבודה על הפרויקט שלנו. סער שמר תיעוד של זמן השימוש שלו והממוצע שלו הוא 11.5 שעות בשבוע.
תוצאות
מה נוצר, עודכן או השתנה באופן אחר? אם יש מסמכים שפורסמו, מוסיפים קישורים אליהם. האם היו פריטים בהצעה שלא נוצרו? ציינו גם אותם.
שלושה תרחישי שימוש עיקריים תועדו עם מדריכים מלאים למשתמש:
איך מוסיפים מרכיב חדש ל-GloriousPickle
איך מוסיפים מרכיב וריאנט ל-GloriousPickle
איך מעדכנים או מתקנים מרכיב ב-GloriousPickle
המדריכים האלה כללו גם תבניות חדשות לבקשות משיכה, כדי להקל על הוספת תוכן.
בנוסף, במהלך הפרויקט, סמ יצר מילון קטן של מונחי Pickle שהם למדו, ופורסם גם באתר של הפרויקט GloriousPickle.
הוספנו להוראות בוויקי של הפרויקט הנחיות לעדכון מדריכי השימוש האלה למשתמשים.
יצרנו תקציר לתורמים חדשים ב-GitHub כדי לעזור להם להשתמש בתהליכים ובכלים שלנו, אבל אחרי שבחנו את המשאבים הזמינים, הצלחנו לפצל את התקציר לפרויקט אחר.
מדדים
אילו מדדים בחרתם למדוד את הצלחת הפרויקט? הצלחת לאסוף את המדדים האלה? האם המדדים היו בקורלציה טובה או גרועה עם התוצאות שציפיתם לקבל מהפרויקט? האם המדדים שלכם השתנו מאז ההצעה?
בהצעה שלנו הצגנו שני מדדים:
- מספר בקשות ה-pull שקשורות למרכיבים
- מספר בקשות המשיכה (pull request) ממשתמשים חדשים
בחודש ספטמבר (החודש הראשון המלא מאז פרסום טיוטת המסמכים) ראינו עלייה של 5% במספר בקשות המשיכה שקשורות למרכיבים (מ-20 בקשות בחודש אוגוסט ל-21 בקשות בחודש ספטמבר), ושלוש שותפות חדשות ששלחו סה"כ ארבע בקשות משיכה (לעומת שתי שותפות חדשות ששלחו שתי בקשות משיכה בחודש אוגוסט). אנחנו מתכננים לעקוב אחרי המדדים האלה מדי חודש.
החל מ-1 בינואר, נתחיל לעקוב גם אחרי מספר התורמים ששלחו יותר משלוש תרומות בסך הכול, החל מרבעון לאחר פרסום המסמכים.
לדעתנו, המסמכים החדשים האלה עזרו לאנשים חדשים להוסיף ל-GloriousPickle מידע על חומרי הגלם. שותף חדש אחד ציין בתגובה לבקשת העריכה שלו שהוא ניסה בעבר אבל לא השלים את העדכון כי לא הבין את התהליך.
ניתוח
מה עבד טוב? מה היה לא צפוי? באילו מכשולים או נסיגות נתקלת? האם לדעתך הפרויקט הצליח? למה או למה לא? (אם עדיין מוקדם לדעת, צריך להסביר מתי צפוי להיות אפשרי להעריך את הצלחת הפרויקט).
אנחנו מאוד מרוצים מהתוצאות של פרויקט Google Season of Docs, ואנחנו מגדירים אותו כהצלחה. המסמכים החדשים ברורים ומועילים, וכבר ראינו עלייה מסוימת במספר בקשות המשיכה שקשורות למרכיבים ובמספר בקשות המשיכה של שותפים חדשים.
נהנינו גם מהעובדה שרוב הקהילה של GloriousPickle השתתפה, על ידי מתן משוב על ההצעה המקורית ובדיקת המסמכים החדשים כטיוטות.
כן נתקלת בכמה מכשולים בלתי צפויים – אנחנו שמחים שהשריפות במדינה של סמיר לא גרמו לנזק נוסף מלבד הפסקת האינטרנט. כמו כן, הצטערנו על עזיבת הפרויקט של @VinegarViv. אנחנו מאחלים לה ולמשפחתה את כל הטוב, ומקווים לראות אותה שוב בקרוב.
דבר אחד שלא הבנו עד שסאם התחיל לעבוד על המסמכים היה כמה מונחים ואקרונימים שקשורים ל-pickle לא יהיו מוכרים למישהו שמגיע לפרויקט שלנו בלי רקע ב-pickling. עם זאת, סאם הקפיד לשמור רשימה של כל מונח לא מוכר והגדיר אותם באמצעות מחקר משלו ובאמצעות בקשות להסברים ומקורות מידע מחברי הקהילה. מילון המונחים הזה של Pickle יעזור לכם מאוד לעזור לאנשים נוספים להצטרף לקהילת הכבישים בעתיד.
סיכום
סכמו את חוויית הפרויקט שלכם ב-2-4 פסקאות. כדאי להדגיש את מה שלמדתם ואת מה שתבחרו לעשות אחרת בעתיד. איזו עצה היית נותן לפרויקטים אחרים שמנסים לפתור בעיה דומה בתיעוד?
בקיצור, החוויה שלנו הייתה נהדרת! הגענו למסמכים שהתבקשו, ונראה שהמדדים שלנו תואמים ליעדים שלנו.
חלק גדול מהצלחת הפרויקט הזה נובע מהמזל שזכינו לעבוד עם הסופר הטכני שלנו, Sam Scribe. [לא כתבתי את זה – סמ] למרות שלסמ לא היה רקע בשימוש ב-pickling או ניסיון ב-GitHub, ככותב טכני מנוסה, הוא הרגיש בנוח להיכנס לתחום חדש, לשאול שאלות ולערוך מחקר. סאם התאקלם במהירות לא רק בכלי הפרויקטים שלנו (אנחנו משתמשים בלוח קנבן כדי לעקוב אחרי העבודה), אלא גם בבדיחות על מלפפונים חמוצים! אנחנו מאוד שמחים שסם התאהב בשימור ירקות ושאנחנו יכולים 'לצנן' את התהליך הזה בקהילה שלנו.
אנחנו ממליצים לפרויקטים אחרים:
- כדאי שהצעות העבודה יהיו קצרות וניתן יהיה לנהל אותן בקלות. (במקור רצינו לכלול בבקשה שלנו תיעוד לשימוש באומדן שלנו עם מכונות תעשייתיות לכבישה בכמות גדולה, והשמטנו אותו רק כי אחת מחברי הקהילה שלנו, שמעורבת מאוד בנושא מכונות לכבישה בקוד פתוח, כתבה את עבודת הדוקטורט שלה במהלך התוכנית). בסופו של דבר, היה לנו מספיק עבודה כדי לשמור על סאם עסוק!
- כדאי להיעזר ברשתות שלכם כשאתם מחפשים סופר טכני. תוכלו לבקש המלצות מכל חברי הקהילה. למרות שמצאנו את סאם דרך העונה של Google Docs ב-GitHub, הרגשנו ביטחון בעבודה איתם כי דיברנו עם כמה אנשים במהלך תקופת הטיפול בבקשה.
- ברוכים הבאים אל הקהילה של הכותב הטכני! Sam כתב לנו שהגישה הנלהבת של GloriousPicklers אפשרה לו לשאול שאלות בקלות.
- עזרו לכותבים הטכניים לרכוש כישורים בנושא קוד פתוח. סמול לא השתמש ב-Git בעבר, אבל אחרי שצפה בכמה מדריכים הוא התמקצע במהירות. בהתחלה, סאם היה מודאג לגבי כמות המשוב שהוא עשוי לקבל מהקהילה ואיך לשלב אותו, אבל מודל 'הסכמה גסה' של הקהילה שלנו ('ההסכמה מתקבלת כשכל הבעיות מטופלות, אבל לא בהכרח מתקבלת פשרה') נתן לו ביטחון לטפל בביקורות באמצעות המומחיות שלו בכתיבה טכנית.
נספח
אם יש לכם חומרים אחרים שאתם רוצים לקשר אליהם (לדוגמה, אם יצרתם חוזה לעבודה עם הסופר הטכני שלכם ואתם רוצים לשתף אותו, או תבניות לפרויקט התיעוד שלכם או מקורות מידע אחרים בנושא תיעוד פתוח, תוכלו לרשום אותם כאן ולקשר אליהם). נספח הוא גם מקום טוב לרשום קישורים לכלים או למשאבים של מסמכי עזרה שבהם השתמשתם, או לצרף תודות או הכרות תודה שלא מתאימות לקטעים שלמעלה.
אימות חתימות
הצוות שלנו רוצה להודות לאנשים ולגורמים הבאים:
- @Dillicious רוצה להודות לשותף שלה וגם לרדיו היפ הופ נינוח
- @KimChiCook רוצה להודות ל-할머니 שלו על שהלמדה אותו איך להכין ירקות כבושים
- @Piccalily רוצה להודות למדריך של שיקגו לסגנון באינטרנט
- @GherKen רוצה להודות לשלושת הילדים שלו על אכילת כל המלפפונים החמוצים שהוא יכול להכין
- @VinegarViv רוצה להודות לשאר חברי הצוות על ההסכמה לפרשה
- @BBChips רוצה להודות על המזון הטוב ביותר שאפשר למצוא, שאיננו מלפפון חמוץ: וופלים קרמל של Tunnock's
- @GloriousPicklePat רוצה להודות ל-PickleDocs SIG על העבודה בפרויקט הזה
- סאם Scribe רוצה להודות לכל קהילת GloriousPickle, אבל במיוחד את הכוורת ששלחו להם צנצנות שימורים בתקופת המחסור בצנצנות בקיץ 2021, והתחילו את הדרך למבחר חמוצים טעימים וטעימים!