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